10 TCCでのアプリケーションの開発

TCCプロトコルでは、トランザクション・イニシエータ・サービスが、他の参加側マイクロサービスにリソースを予約するように求めます。イニシエータとすべての参加側が必要な予約を取得すると、イニシエータは次に、すべての予約を確定するようにMicroTxにリクエストを送信します。

TCCトランザクション・プロトコルを使用するカスタム・アプリケーションを開発するためのガイドライン

イニシエータ・サービスがビジネス・ロジックに基づいて、行われた予約が必要ない(使用できない)と判断すると、すべての予約を取り消すようにMicroTxにリクエストします。予約の内容はアプリケーションによって異なります。

TCCトランザクション・プロトコルは、基本のHTTP動詞(POSTPUTおよびDELETE)に依存します。アプリケーションが次のガイドラインに準拠していることを確認します:

  • トランザクション・イニシエータ・サービスは、POST HTTPメソッドを使用して新しい予約を作成する必要があります。このリクエストへのレスポンスとして、トランザクション参加側サービスは予約を表すURIを返す必要があります。MicroTxクライアント・ライブラリは、MicroTx固有のヘッダーにそのURIを配置して、URIがコール・スタックに伝播されるようにします。
  • このプロトコルは参加側サービスに依存して、確実にすべての参加側サービスが予約を確定するか取り消すようにします。URIは、予約を確定するためにPUT HTTPメソッドに応答し、予約を取り消すにはDELETE HTTPメソッドに応答する必要があります。

10.1 TCCでアプリケーションを開発するワークフロー

MicroTxを使用してTCCトランザクションを管理するアプリケーションを開発するには、次のワークフローをガイドとして使用します。

タスク 説明 詳細
MicroTxをインストールします MicroTxをインストールし、アクセスできることを確認します。 MicroTxをインストールして使用するワークフロー
MicroTxライブラリ・プロパティの構成情報を指定します。 すべてのトランザクション参加側アプリケーションおよびトランザクション・イニシエータ・アプリケーションに対してこのステップを実行し、アプリケーションがライブラリにアクセスできるようにします。 ライブラリ・プロパティの構成
MicroTxライブラリをアプリケーション・コードと統合します。 次の要因に基づいて、ライブラリを統合する適切な手順を選択します:
  • アプリケーションの開発フレームワーク
  • アプリケーションがトランザクションを開始するか、トランザクションに参加するか
ライブラリにはJava、Node.js、およびPythonアプリケーション用があります。次のタスクのいずれかを実行します。
アプリケーションのデプロイ マイクロサービスの開発、テストおよびデプロイを個別に行います。ライブラリ・ファイルをアプリケーションに統合した後で、アプリケーションをデプロイします。 アプリケーションのデプロイ

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

環境変数名では大/小文字が区別されることに注意してください。

10.3 トランザクションのタイムアウトについて

リクエストをアクティブにしておく期間を指定します。この値は、TCCトランザクションに参加する各マイクロサービスに固有です。トランザクションが、指定した期間内にマイクロサービスによって確定または取り消されない場合、トランザクションは取り消されます。

TCCトランザクションでは、トランザクション・イニシエータ・サービスが、すべての参加側サービスの予約のステータスを収集し、トランザクションを確定するか取り消すかを決定します。また、MicroTxによって、すべての参加側サービスが予約を確定するか取り消すことが保証されます。MicroTxがトランザクションを確定するリクエストを送信したとき、一部の参加側サービスがトランザクションを確定しても、それ以外の参加側サービスでトランザクションがタイムアウトすることがあります。トランザクションがタイムアウトした場合に備え、予約を取り消してリソースを解放するために必要なコードを用意するのは、アプリケーション開発者の責任です。MicroTxは、トランザクション・イニシエータのビジネス・ロジックで行われた決定に基づいて、予約を確定するか取り消すリクエストをすべての参加側サービスに送信します。

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ライブラリのプロパティ値を構成していることを確認してください。

  1. MicroTxライブラリをアプリケーションのpom.xmlファイルにmaven依存関係として含めます。次のサンプル・コードは22.3リリース用です。使用するリリースに基づいて、正しいバージョンを指定してください。
    <dependency>
         <groupId>com.oracle.tmm.jta</groupId>
         <artifactId>TmmLib</artifactId>
         <version>22.3</version>
    </dependency>
  2. イニシエータ・アプリケーション・リソース・クラスの前に@TCC注釈を追加します。これにより、新しいTCCトランザクションが開始され、トランザクション・イニシエータからのすべての送信REST APIリクエストにヘッダーが追加されます。

    次のコードを使用して、トランザクション・イニシエータ・サービスに対してコールが行われたときに新しいTCCトランザクションを開始します。次の例では、サービスを開始するコードがクラスmyTransactionInitiatorAppに含まれています。ご自身の環境に基づいてクラス名を置き換えます。

    import oracle.trm.tcc.annotation.TCC;
    @TCC(timeLimit = 120, timeUnit = ChronoUnit.SECONDS)  //Add @TCC annotation before the initiator application resource class to start a TCC transaction
    public class myTransactionInitiatorApp {
        // Service code that is specific to the transaction initiator service.
    }

    @TCC注釈を使用して、次のオプション・パラメータを指定できます。

    • timeLimit: トランザクション・イニシエータ・サービスでリソースを予約する期間を整数で指定します。期限切れになった後でリソースを解放してTCCトランザクションのその部分を取り消すために必要なコードを用意するのは、アプリケーション開発者の責任です。業務要件に基づいて期限を決めてください。
    • timeUnit: 指定する期限の単位(ChronoUnit.SECONDSChronoUnit.MINUTESなど)を指定します。指定できる値は、java.time.temporal.ChronoUnitクラスのすべての列挙値です。https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.htmlを参照してください。

10.4.2 トランザクション参加側としてのJavaアプリケーションの構成

開始する前に、MicroTxライブラリのプロパティ値を構成していることを確認してください。

  1. MicroTxライブラリをアプリケーションのpom.xmlファイルにmaven依存関係として含めます。次のサンプル・コードは22.3リリース用です。使用するリリースに基づいて、正しいバージョンを指定してください。
    <dependency>
         <groupId>com.oracle.tmm.jta</groupId>
         <artifactId>TmmLib</artifactId>
         <version>22.3</version>
    </dependency>
  2. トランザクション参加側アプリケーション・コードにTCC注釈を挿入します。
    参加側サービスが既存のTCCトランザクションに参加できるようにするには、トランザクション参加側サービスのリソース・クラスの前に@TCC注釈を追加します。

    次のコードをトランザクション参加側コードに挿入します。次の例では、myTransactionParticipantAppクラスにトランザクション参加側サービスのコードが含まれています。ご自身の環境に基づいてクラス名を置き換えます。

    import oracle.trm.tcc.annotation.TCC;
    import javax.ws.rs.core.Application;
     
    @Path("/")
    @TCC(timeLimit = 120, timeUnit = ChronoUnit.SECONDS)
    //Add @TCC annotation so that the transaction participant service joins an existing TCC transaction
    //The transaction initiator service passes the TCC context in the request header.
    public class myTransactionParticipantApp extends Application {
        // Service code that is specific to the transaction participant service. 
    }
  3. トランザクション参加側アプリケーション・コードで、addTccParticipant(String uri)メソッドをコールして、参加側サービスをTCCトランザクションに登録します。参加側サービスは、MicroTxがトランザクションの確定または取消しに使用するURIを公開します。MicroTxは、トランザクションを確定するためにPUTメソッドをコールし、トランザクションを取り消して予約済リソースを解放するためにDELETEメソッドをコールします。これらのメソッドが存在し、確定と取消しのロジックが実装されていることを確認します。トランザクションを確定または取り消すために、MicroTxはすべての参加側サービスの公開URIにコールを送信します。

    次のコード例は、参加側アプリケーション・コードに加える必要がある変更を示しています。

    
    public class myTransactionParticipantApp extends Application {
        // Service code that is specific to the transaction participant service. 
    
        @POST
        //The REST endpoint of the transaction participant service.
        @Path("bookings")
        @Consumes(MediaType.APPLICATION_JSON)
        public Response create() throws TccUnknownTransactionException
        // Business logic to create a booking.
          String bookingUri;
          // Register participant service with the TCC transaction
          TccClient.addTccParticipant(bookingUri.toString());
        }
    
        @PUT
        @Path("bookings/{bookingId}")
        @Consumes(MediaType.APPLICATION_JSON)
        public Response confirm() throws TccUnknownTransactionException {
        //Application-specific code to confirm the booking.
        }
     
        @DELETE
        @Path("bookings/{bookingId}")
        @Consumes(MediaType.APPLICATION_JSON)
        public Response cancel() throws TccUnknownTransactionException {
        //Application-specific code to cancel the booking.
        }          
    }

    説明

    • myTransactionParticipantAppは、トランザクション参加側サービスのコードを含むクラスです。このクラスには、参加側サービスがトランザクションの確定または取消しに使用するユーザー定義メソッドがすでに含まれています。
    • bookingsは、トランザクション参加側サービスのRESTエンドポイントです。トランザクション・イニシエータ・サービスがこのエンドポイントをコールして、ホテル予約の作成などのタスクを実行します。
    • bookingUriには、参加側サービスが公開するリソースURIと、MicroTxがトランザクションの確定または取消しに使用するリソースURIが含まれます。
    • bookingIdは、確定するか取り消す予約の一意IDです。
  4. 変更内容を保存します。
このような変更をすべてのトランザクション参加側サービスのコードで行ってください。

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ライブラリのプロパティ値を構成していることを確認してください。

  1. Node.jsのMicroTxライブラリをpackage.jsonファイルに依存関係として追加します。
    "dependencies": {
        "tmmlib-node": "file:tmmlib-node-<version>.tgz"
      }
  2. プロパティ値を定義したtmm.propertiesファイルを渡して、マイクロサービスのMicroTxライブラリ・プロパティを構成します。
    TrmConfig.init('./tmm.properties');
  3. MicroTxライブラリおよびexpressモジュール・ファイルをインポートします。
    import {HttpMethod, TrmConfig} from "tmmlib-node/util/trmutils";
    import {TCCConfig} from "tmmlib-node/tcc/tcc";
    import {NextFunction, request, Request, Response, Router} from 'express';
  4. ルーター・オブジェクトを作成します。
    次のコードを使用して、svcRouterという名前のルーター・オブジェクトを作成します。
    const svcRouter = Router();
  5. 次のコードを追加して、トランザクション・イニシエータ・サービスのRESTエンドポイントのTCCConfigオブジェクトを初期化します。トランザクション・イニシエータによって多数のREST APIエンドポイントが公開されることがありますが、TCCConfigオブジェクトを初期化する必要があるのは、TCCトランザクションに参加する必要があるREST APIエンドポイントのみです。

    次のコード・サンプルでは、トランザクション・イニシエータ・アプリケーションは/bookings REST APIエンドポイントを公開しています。

    // Initialize TCCConfig object for all the endpoints which need to participant in the TCC transaction.
    const tccConfig: TCCConfig = new TCCConfig("/bookings", svcRouter, HttpMethod.POST, 30);

    説明

    • svcRouterは、前のステップで作成したルーター・オブジェクトです。
    • 30は、トランザクション・イニシエータ・アプリケーションがリソースを予約する時間制限(秒)です。期間は整数で指定します。期限切れになった後でリソースを解放してTCCトランザクションのその部分を取り消すために必要なコードを用意するのは、アプリケーション開発者の責任です。業務要件に基づいて期限を決めてください。

    これらの値は、ご使用の環境に固有の値で置き換えてください。

    このコードを実行すると、TCCトランザクションが開始され、MicroTxによって、指定したREST APIエンドポイントからのすべての送信リクエストのヘッダーが追加されます。

10.5.2 トランザクション参加側としてのNode.jsアプリケーションの構成

開始する前に、MicroTxライブラリのプロパティ値を構成していることを確認してください。

  1. Node.jsのMicroTxライブラリをpackage.jsonファイルに依存関係として追加します。
    "dependencies": {
        "tmmlib-node": "file:tmmlib-node-<version>.tgz"
      }
  2. プロパティ値を定義したtmm.propertiesファイルを渡して、マイクロサービスのMicroTxライブラリ・プロパティを構成します。
    TrmConfig.init('./tmm.properties');
  3. MicroTxライブラリおよびexpressモジュール・ファイルをインポートします。
    import {HttpMethod, TrmConfig} from "tmmlib-node/util/trmutils";
    import {TCCConfig} from "tmmlib-node/tcc/tcc";
    import {NextFunction, request, Request, Response, Router} from 'express';
  4. ルーター・オブジェクトを作成します。
    次のコードを使用して、svcRouter2という名前のルーター・オブジェクトを作成します。
    const svcRouter2 = Router();
  5. 次のコードを追加して、トランザクション参加側サービスの確定および取消しREST APIエンドポイントのTCCConfigオブジェクトを初期化します。

    次のコード・サンプルでは、トランザクション参加側アプリケーションは/bookings REST APIエンドポイントを公開しています。svcRouter2は、前のステップで作成したルーター・オブジェクトです。これらの値は、ご使用の環境に固有の値で置き換えてください。

    //Initialize TCCConfig object for all the endpoints which need to participant in the TCC transaction
    const tccConfig: TCCConfig = new TCCConfig("/bookings", svcRouter2, HttpMethod.POST, 30);

    説明

    • /bookingsは、トランザクション参加側サービスが公開するREST APIエンドポイントです。

    • svcRouter2は、事前に作成しておいたルーター・オブジェクトです。

  6. 次のコード・サンプルでは、トランザクション参加側サービスは、トランザクションの確定または取消しのために/bookings/:bookingId REST APIエンドポイントを公開しています。これらの値は、ご使用の環境に固有の値で置き換えてください。また、これらのエンドポイントがトランザクション参加側サービスに存在し、確定と取消しのロジックがコードに実装されていることも確認します。dohotelBooking()doConfirmBooking()およびdoCancelBooking()メソッドには、それぞれ、リソースの作成、トランザクションの確定、トランザクションの取消しのビジネス・ロジックが含まれています。ビジネス・ロジックがトランザクション参加側サービスのコードに実装され、エンドポイントが存在することを確認します。

    また、REST APIエンドポイントで使用されるHTTPメソッドも記述します。MicroTxでは、PUTメソッドを使用してトランザクションを確定し、DELETEメソッドを使用してトランザクションを取り消し、指定されたリソースURI用に予約されたリソースを解放します。

    svcRouter.post('/bookings', asyncHandler(async (req: Request, res: Response) => {
        dohotelBooking(req, res); //app-specific code to create a resource
    }));
    
    svcRouter.put('/bookings/:bookingId', asyncHandler(async (req: Request, res: Response) => {
        doConfirmBooking(req, res); //app-specific code to confirm the transaction
    }));
    
    svcRouter.delete('/bookings/:bookingId', asyncHandler(async (req: Request, res: Response) => {
        doCancelBooking(req, res); //app-specific code to cancel the transaction
    }));
  7. 前に作成したTCCConfigオブジェクトを使用して、参加側(予約済リソースURI)を既存のTCCトランザクションに登録します。これには、このリソースURIを使用してaddTccParticipantメソッドをコールします。
    const bookingUri;
    tccConfig.addTccParticipant(bookingUri);

    このコードが実行されると、イニシエータ・サービスが参加側サービスをコールしたときに、参加側サービスが既存のTCCトランザクションに参加します。また、MicroTxライブラリは、確定エンドポイントおよび取消しエンドポイントとして指定されたURIを使用して参加側サービスを登録します。

10.6 TCCでのPythonアプリケーションの開発

MicroTxリリース22.3.2以降で、Pythonアプリケーション用のMicroTxクライアント・ライブラリは、新しいTCCトランザクションを開始したり、既存のTCCトランザクションに参加したりする機能を提供します。

MicroTxを使用してTCCトランザクションを管理するには、Pythonアプリケーション・コードを更新して、MicroTxクライアント・ライブラリによって提供される機能を統合します。

次の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アプリケーションの構成

PythonアプリケーションのフレームワークとしてFlaskまたはDjangoを選択できます。この項では、MicroTxライブラリを、Pythonアプリケーション(Flaskフレームワーク)のアプリケーション・コードと統合する手順について説明します。
  1. Pythonアプリケーション用に作成した仮想環境でターミナルを開いてから、次のコマンドを実行してPython用のMicroTxライブラリ・ファイル(installation_directory/otmm-<version>/lib/pythonフォルダ)をインストールします。
    pip3 install tmmpy-<version>.whl
  2. MicroTxライブラリのプロパティ値を構成します。新しいファイルを作成してtmm.propertiesとして保存します。次のプロパティに値を指定する必要があります。

    次の例では、プロパティのサンプル値を指定しています。ご自身の環境に基づいて値を指定してください。

    oracle.tmm.TcsUrl = http://tmm-app:9000/api/v1
    oracle.tmm.PropagateTraceHeaders = true
    server.port = 8080
    oracle.tmm.CallbackUrl = http://localhost:{server.port}

    各プロパティの詳細は、「ライブラリ・プロパティの構成」を参照してください。

    このファイルの名前と場所を書き留めてください。後でtccConfigオブジェクトを初期化するときに指定する必要があります。

  3. MicroTxのライブラリおよび例外をインポートします。tcclib.exceptionを使用して例外を処理できます。
    from tcclib.tcc import TCCClient, Middleware, http_request, TCCConfig
    import tcclib.exception as ex
  4. ミドルウェアを含むFlaskインスタンスを作成します。ミドルウェアは、Flaskインスタンスによって受信されるすべての受信リクエストのインターセプトに役立ちます。
    次のサンプル・コードによって、Flaskインスタンスとミドルウェア・オブジェクトが作成されます。
    # Create a Flask instance with the name of the current module.
    app = Flask(__name__)
    # Middleware helps to intercept all the incoming requests received by the Flask application.
    app.wsgi_app = middleware(app.wsgi_app)
  5. 次のコードを追加して、マイクロサービスのtccConfigオブジェクトを初期化します。

    構文

    tccConfig = TCCConfig(filePath=<application_properties_file_path>, timeLimitInSeconds=<integer>)

    サンプル

    tccConfig = TCCConfig(filePath="./tmm.properties", timeLimitInSeconds=300)

    説明

    • ./tmm.propertiesは、前にトランザクション・イニシエータ・サービスのMicroTxライブラリ・プロパティの値を定義したファイルの場所です。
    • 300は、トランザクション・イニシエータ・サービスがリソースを予約する時間制限(秒)です。期間は整数で指定します。期限切れになった後でリソースを解放してTCCトランザクションのその部分を取り消すために必要なコードを用意するのは、アプリケーション開発者の責任です。業務要件に基づいて期限を決めてください。

    これらの値は、ご使用の環境に固有の値で置き換えてください。

  6. TCCトランザクション・プロトコルは、基本のHTTP動詞(POSTPUTおよびDELETE)に依存します。各HTTPメソッドのREST APIエンドポイントを公開し、これらのエンドポイントを、ビジネス・ロジックを実行する特定の関数にマップする必要があります。アプリケーション・コードには、新しい予約を作成し、予約を確定するか取り消すためのビジネス・ロジックがすでに含まれています。app.routeデコレータを使用して、アプリケーション内の関数をHTTP動詞とURLパスにバインドします。

    トランザクション・イニシエータ・サービスの次のコード・サンプルで、サービスは様々なHTTP動詞のREST APIエンドポイントを公開しています。

    //Mandatory. The transaction initiator service must use the 
    //POST HTTP method to create a new reservation.
    @app.route('/travel-agent/api/bookings/reserve', methods=['POST'])
    def do_trip_reserve(): 
         //app-specific code to create a booking
    
    //Mandatory. Use the PUT HTTP method to confirm a reservation.
    @app.route('/travel-agent/api/confirm/<trip_booking_id>', methods=['PUT'])
    def do_trip_confirm(trip_booking_id):
         //app-specific code to confirm the specified booking ID
    
    //Mandatory. Use the DELETE HTTP method to cancel a reservation.
    @app.route('/travel-agent/api/cancel/<trip_booking_id>', methods=['DELETE'])
    def do_trip_cancel(trip_booking_id):
         //app-specific code to delete the specified booking ID
    

    説明

    • /travel-agent/api/bookings/reserve, /travel-agent/api/confirm/<trip_booking_id>および/travel-agent/api/cancel/<trip_booking_id>は、トランザクション・イニシエータ・サービスが公開するREST APIエンドポイントです。これらのエンドポイントがトランザクション・イニシエータ・サービスに存在し、確定と取消のロジックがコードに実装されていることを確認します。
    • do_trip_reserve()do_trip_confirm()、およびdo_trip_cancel()メソッドには、予約の作成、予約の確定、予約の取消しを行うビジネス・ロジックがそれぞれ含まれています。ビジネス・ロジックがトランザクション・イニシエータ・サービスのコードに実装され、エンドポイントが存在することを確認します。

10.6.2 トランザクション参加側としてのPythonアプリケーションの構成

PythonアプリケーションのフレームワークとしてFlaskまたはDjangoを選択できます。この項では、MicroTxライブラリを、Pythonアプリケーション(Flaskフレームワーク)のアプリケーション・コードと統合する手順について説明します。
  1. Pythonアプリケーション用に作成した仮想環境でターミナルを開いてから、次のコマンドを実行してPython用のMicroTxライブラリ・ファイル(installation_directory/otmm-<version>/lib/pythonフォルダ)をインストールします。
    pip3 install tmmpy-<version>.whl
  2. MicroTxライブラリのプロパティ値を構成します。新しいファイルを作成してtmm.propertiesとして保存します。次のプロパティに値を指定する必要があります。

    次の例では、プロパティのサンプル値を指定しています。ご自身の環境に基づいて値を指定してください。

    oracle.tmm.PropagateTraceHeaders = true
    server.port = 8080
    oracle.tmm.CallbackUrl = http://localhost:{server.port}

    各プロパティの詳細は、「ライブラリ・プロパティの構成」を参照してください。

    後で指定する必要があるため、このファイルの名前を書き留めてください。

  3. MicroTxのライブラリおよび例外をインポートします。tcclib.exceptionを使用して例外を処理できます。
    from tcclib.tcc import TCCClient, Middleware, http_request, TCCConfig
    import tcclib.exception as ex
  4. Flaskアプリケーションとミドルウェア・オブジェクトを作成します。
    次のサンプル・コードによって、appという名前のFlaskアプリケーションとミドルウェア・オブジェクトが作成されます。ミドルウェア・オブジェクトはFlaskアプリケーションをラップし、Flaskアプリケーションによって受信されるすべての受信リクエストをインターセプトします。
    # Create an instance of the Flask class with the name of the current module.
    app = Flask(__name__)
    # Create a middleware object to wrap around the Flask application that you have created.
    # The middleware object intercepts all the incoming requests received by the Flask application.
    app.wsgi_app = middleware(app.wsgi_app)
  5. 次のコードを追加して、マイクロサービスのtccConfigオブジェクトを初期化します。

    構文

    tccConfig = TCCConfig(filePath=<application_properties_file_path>, timeLimitInSeconds=<integer>)

    サンプル

    tccConfig = TCCConfig(filePath="./tmm.properties", timeLimitInSeconds=300)

    説明

    • ./tmm.propertiesは、トランザクション参加側サービスのMicroTxライブラリ・プロパティの値を定義したファイルの場所です。
    • 300は、トランザクション参加側サービスがリソースを予約する時間制限(秒)です。期間は整数で指定します。期限切れになった後でリソースを解放してTCCトランザクションのその部分を取り消すために必要なコードを用意するのは、アプリケーション開発者の責任です。業務要件に基づいて期限を決めてください。

    これらの値は、ご使用の環境に固有の値で置き換えてください。

  6. 前に作成したTCCConfigオブジェクトを使用して、参加側(予約済リソースURI)を既存のTCCトランザクションに登録します。これには、このリソースURIを使用してaddTccParticipantメソッドをコールします。
    const bookingUri;
    tccConfig.addTccParticipant(bookingUri);

    このコードが実行されると、イニシエータ・サービスが参加側サービスをコールしたときに、参加側サービスが既存のTCCトランザクションに参加します。また、MicroTxライブラリは、確定エンドポイントおよび取消しエンドポイントとして指定されたURIを使用して参加側サービスを登録します。