10 TCCでのアプリケーションの開発
TCCプロトコルでは、トランザクション・イニシエータ・サービスが、他の参加側マイクロサービスにリソースを予約するように求めます。イニシエータとすべての参加側が必要な予約を取得すると、イニシエータは次に、すべての予約を確定するようにMicroTxにリクエストを送信します。
TCCトランザクション・プロトコルを使用するカスタム・アプリケーションを開発するためのガイドライン
イニシエータ・サービスがビジネス・ロジックに基づいて、行われた予約が必要ない(使用できない)と判断すると、すべての予約を取り消すようにMicroTxにリクエストします。予約の内容はアプリケーションによって異なります。
TCCトランザクション・プロトコルは、基本のHTTP
動詞(POST
、PUT
およびDELETE
)に依存します。アプリケーションが次のガイドラインに準拠していることを確認します:
- トランザクション・イニシエータ・サービスは、
POST
HTTPメソッドを使用して新しい予約を作成する必要があります。このリクエストへのレスポンスとして、トランザクション参加側サービスは予約を表すURIを返す必要があります。MicroTxクライアント・ライブラリは、MicroTx固有のヘッダーにそのURIを配置して、URIがコール・スタックに伝播されるようにします。 - このプロトコルは参加側サービスに依存して、確実にすべての参加側サービスが予約を確定するか取り消すようにします。URIは、予約を確定するために
PUT
HTTPメソッドに応答し、予約を取り消すにはDELETE
HTTPメソッドに応答する必要があります。
- TCCでアプリケーションを開発するワークフロー
MicroTxを使用してTCCトランザクションを管理するアプリケーションを開発するには、次のワークフローをガイドとして使用します。 - ライブラリ・プロパティの構成
MicroTxクライアント・ライブラリ・プロパティの構成情報を指定します。すべての参加側アプリケーションおよびイニシエータ・アプリケーションに対してこのステップを実行する必要があります。 - トランザクションのタイムアウトについて
リクエストをアクティブにしておく期間を指定します。この値は、TCCトランザクションに参加する各マイクロサービスに固有です。トランザクションが、指定した期間内にマイクロサービスによって確定または取り消されない場合、トランザクションは取り消されます。 - TCCでのJavaアプリケーションの開発
MicroTxライブラリは、JAX-RSフィルタを使用して受信HTTPコールをインターセプトしてから、新しいTCCトランザクションを開始するか、既存のトランザクションに参加します。 - TCCでのNode.jsアプリケーションの開発
- TCCでのPythonアプリケーションの開発
MicroTxリリース22.3.2以降で、Pythonアプリケーション用のMicroTxクライアント・ライブラリは、新しいTCCトランザクションを開始したり、既存のTCCトランザクションに参加したりする機能を提供します。
10.1 TCCでアプリケーションを開発するワークフロー
MicroTxを使用してTCCトランザクションを管理するアプリケーションを開発するには、次のワークフローをガイドとして使用します。
タスク | 説明 | 詳細 |
---|---|---|
MicroTxをインストールします | MicroTxをインストールし、アクセスできることを確認します。 | MicroTxをインストールして使用するワークフロー |
MicroTxライブラリ・プロパティの構成情報を指定します。 | すべてのトランザクション参加側アプリケーションおよびトランザクション・イニシエータ・アプリケーションに対してこのステップを実行し、アプリケーションがライブラリにアクセスできるようにします。 | ライブラリ・プロパティの構成 |
MicroTxライブラリをアプリケーション・コードと統合します。 | 次の要因に基づいて、ライブラリを統合する適切な手順を選択します:
|
ライブラリにはJava、Node.js、およびPythonアプリケーション用があります。次のタスクのいずれかを実行します。 |
アプリケーションのデプロイ | マイクロサービスの開発、テストおよびデプロイを個別に行います。ライブラリ・ファイルをアプリケーションに統合した後で、アプリケーションをデプロイします。 | アプリケーションのデプロイ |
親トピック: TCCでのアプリケーションの開発
10.2 ライブラリ・プロパティの構成
MicroTxクライアント・ライブラリ・プロパティの構成情報を指定します。すべての参加側アプリケーションおよびイニシエータ・アプリケーションに対してこのステップを実行する必要があります。
tmm.properties
ファイルを開き、次のパラメータの値を入力してMicroTxライブラリを構成します。-
oracle.tmm.TcsUrl
: MicroTxアプリケーションにアクセスするためのURLを入力します。「MicroTxへのアクセス」を参照してください。この値はトランザクション・イニシエータ・アプリケーションの場合に入力する必要があります。トランザクション参加側アプリケーションの場合、この値を指定する必要はありません。 -
oracle.tmm.PropagateTraceHeaders
: トランザクションを全面的にトレースする場合は、これをtrue
に設定します。これにより、すべての受信リクエストおよび送信リクエストのトレース・ヘッダーが伝播されます。Helidonベースのマイクロサービスの場合、Helidonフレームワークがデフォルトでトレース・ヘッダーを伝播するため、トレース・ヘッダーを2回伝播しないように、このプロパティをfalse
に設定します。このプロパティをtrueに設定できるのは、Helidon構成でトレース・ヘッダーの伝播が無効になっているときに、MicroTxを使用して分散トレースを有効にする場合です。その他のマイクロサービスの場合は、このプロパティをtrue
に設定します。 server.port
: マイクロサービスへのアクセスに使用するポートを入力します。このポートでインバウンドおよびアウトバウンド・トラフィックを許可するために必要なネットワーク・ルールを作成します。たとえば、8080
です。-
oracle.tmm.CallbackUrl
: 参加側サービスのURLを入力します。MicroTxは、指定されたURLを使用して参加側サービスに接続します。この値を次の形式で指定します。https://externalHostnameOfApp:externalPortOfApp/
説明externalHostnameOfApp
: イニシエータ・サービスまたは参加側サービスの外部ホスト名。たとえば、bookTicket-app
です。externalPortOfApp
: 参加側サービスにリモートでアクセスできるポート番号。たとえば、8081
です。
MicroTxコーディネータがDockerコンテナ(Ubuntu 20またはDocker Engine 20)内で実行されており、ネットワーク設定が
{--add-host host.docker.internal:host-gateway}
の場合、コールバックURLはhttp://host.docker.internal:{server.port}
です。他のDocker環境では、URLの構造はオペレーティング・システムとそのバージョンによって異なる場合があります。
oracle.tmm.TcsUrl = http://tmm-app:9000/api/v1
oracle.tmm.PropagateTraceHeaders = true
oracle.tmm.CallbackUrl = https://bookTicket-app:8081
server.port = 8081
アプリケーションとMicroTxが同じKubernetesクラスタ内にある場合はHTTPプロトコルを使用し、それ以外の場合はHTTPSプロトコルを使用します。
これらの構成値を環境変数として指定することもできます。application.properties
ファイルと環境変数の両方に値を指定した場合、環境変数に設定されている値がプロパティ・ファイルの値をオーバーライドすることに注意してください。
次の例は、環境変数を構成するためのサンプル値を示しています。
export ORACLE_TMM_TCS_URL = http://tmm-app:9000/api/v1
export ORACLE_TMM_PROPAGATE_TRACE_HEADERS = true
環境変数名では大/小文字が区別されることに注意してください。
親トピック: TCCでのアプリケーションの開発
10.3 トランザクションのタイムアウトについて
リクエストをアクティブにしておく期間を指定します。この値は、TCCトランザクションに参加する各マイクロサービスに固有です。トランザクションが、指定した期間内にマイクロサービスによって確定または取り消されない場合、トランザクションは取り消されます。
TCCトランザクションでは、トランザクション・イニシエータ・サービスが、すべての参加側サービスの予約のステータスを収集し、トランザクションを確定するか取り消すかを決定します。また、MicroTxによって、すべての参加側サービスが予約を確定するか取り消すことが保証されます。MicroTxがトランザクションを確定するリクエストを送信したとき、一部の参加側サービスがトランザクションを確定しても、それ以外の参加側サービスでトランザクションがタイムアウトすることがあります。トランザクションがタイムアウトした場合に備え、予約を取り消してリソースを解放するために必要なコードを用意するのは、アプリケーション開発者の責任です。MicroTxは、トランザクション・イニシエータのビジネス・ロジックで行われた決定に基づいて、予約を確定するか取り消すリクエストをすべての参加側サービスに送信します。
親トピック: TCCでのアプリケーションの開発
10.4 TCCでのJavaアプリケーションの開発
MicroTxライブラリは、JAX-RSフィルタを使用して受信HTTPコールをインターセプトしてから、新しいTCCトランザクションを開始するか、既存のトランザクションに参加します。
次の注釈を使用して、アプリケーション・コードにTCC機能を追加し、参加側サービスを登録します。
@TCC(timeLimit = 120, timeUnit = ChronoUnit.SECONDS)
これを使用して、MicroTxが新しいTCCトランザクションを開始または既存のトランザクションに参加するためにコールするアプリケーション固有のRESTリソースに注釈を付けます。
注釈をクラスに追加すると、JAX-RSフィルタがその注釈を探して、TCCトランザクションに参加するクラスを識別します。リクエスト・ヘッダーにlink
の値が含まれていない場合、MicroTxライブラリは、リクエスト・ヘッダーにlink
の値と一意のトランザクションIDを作成します。一意のトランザクションIDを使用して、トランザクションの識別、トレースまたはデバッグを行うことができます。
リクエスト・ヘッダーにlink
の値が含まれている場合、アプリケーションは既存のTCCトランザクションに参加します。トランザクションに参加するすべてのアプリケーションが、一意のTCCトランザクションIDを共有します。リクエスト・ヘッダーのlink
の値の例を次に示します:
link=[<http://tmm-app:9000/api/v1/tcc-transaction/7ff...>; rel="https://otmm.oracle.com/tcc-transaction/internal",<http://tmm-app:9000/api/v1/tcc-transaction/7ff...>; rel="https://otmm.oracle.com/tcc-transaction/external"]
ここで、7ff...
が一意のトランザクションIDです。値の例は、読みやすくするために...
を使用して一部を省いています。ご使用の環境でヘッダーを確認すると、値全体が表示されます。
10.4.1 トランザクション・イニシエータとしてのJavaアプリケーションの構成
開始する前に、MicroTxライブラリのプロパティ値を構成していることを確認してください。
親トピック: TCCでのJavaアプリケーションの開発
10.4.2 トランザクション参加側としてのJavaアプリケーションの構成
開始する前に、MicroTxライブラリのプロパティ値を構成していることを確認してください。
親トピック: TCCでのJavaアプリケーションの開発
10.5 TCCでのNode.jsアプリケーションの開発
次の TCCヘルパーメソッドを使用して、トランザクションを確定するか取り消します。イニシエータ・サービスと参加側サービスのどちらもヘルパー・メソッドにアクセスできます。
ヘルパー・メソッド | 説明 |
---|---|
ConfirmTCC(req.headers); |
現在のTCCトランザクションを確定します。 |
CancelTCC(req.headers); |
現在のTCCトランザクションを取り消します。 |
GetTCCId(req.headers) |
現在のTCCトランザクションIDを取得します。 |
10.5.1 トランザクション・イニシエータとしてのNode.jsアプリケーションの構成
開始する前に、MicroTxライブラリのプロパティ値を構成していることを確認してください。
親トピック: TCCでのNode.jsアプリケーションの開発
10.5.2 トランザクション参加側としてのNode.jsアプリケーションの構成
開始する前に、MicroTxライブラリのプロパティ値を構成していることを確認してください。
親トピック: TCCでのNode.jsアプリケーションの開発
10.6 TCCでのPythonアプリケーションの開発
MicroTxリリース22.3.2以降で、Pythonアプリケーション用のMicroTxクライアント・ライブラリは、新しいTCCトランザクションを開始したり、既存のTCCトランザクションに参加したりする機能を提供します。
次のTCCClient
ヘルパーメソッドを使用して、トランザクションを確定するか取り消します。イニシエータ・サービスと参加側サービスのどちらもヘルパー・メソッドにアクセスできます。
メソッド | 説明 |
---|---|
ConfirmTCC(incoming_request_headers); |
現在のTCCトランザクションを確定し、HTTPレスポンスを返します。 |
CancelTCC(incoming_request_headers); |
現在のTCCトランザクションを取り消し、HTTPレスポンスを返します。 |
GetTCCId(incoming_request_headers) |
現在のTCCトランザクションIDの詳細を取得します。 |
ここで、incoming_request_headers
は、キーと値のペアのディクショナリです。
10.6.1 トランザクション・イニシエータとしてのPythonアプリケーションの構成
親トピック: TCCでのPythonアプリケーションの開発
10.6.2 トランザクション参加側としてのPythonアプリケーションの構成
親トピック: TCCでのPythonアプリケーションの開発