5.4. API プロバイダーインテグレーションのオペレーションフローの定義

REST API サービスを定義する OpenAPI ドキュメントは、サービスが実行できるオペレーションを定義します。API プロバイダーインテグレーションの作成後、各オペレーションのフローを編集できます。

各オペレーションには必ず 1 つのフローがあります。オペレーションフローでは、コネクションを他のアプリケーションやサービスに追加でき、コネクション間のデータで操作するステップも追加できます。

オペレーションフローへ追加すると、API プロバイダーインテグレーションがベースとする OpenAPI ドキュメントの更新が必要であることがあります。これには、API プロバイダーインテグレーションを編集するページの右上にある View/Edit API Definition をクリックします。これにより、API Designer エディターにドキュメントが表示されます。OpenAPI 定義では、各オペレーションに固有の operationId プロパティーがある限り、API Designer に更新を保存することができ、Fuse Online は API プロバイダーインテグレーションのフロー定義を同期して更新が反映されるようにすることができます。

前提条件

  • API プロバイダーインテグレーションを作成し、名前を付け、保存している必要があります。
  • オペレーションフローが接続する各アプリケーションまたはサービスへのコネクションが作成済みである必要があります。詳細は、コネクションの作成に関する情報 を参照してください。
  • Fuse Online は API が定義するオペレーションのリストを表示します。

手順

  1. Operations リストページで、定義するフローのオペレーションに対して Create flow をクリックします。
  2. このフローに追加する各コネクションに対して以下を行います。

    1. フロービジュアライゼーションで、プラス記号をクリックしてその場所にコネクションを追加します。
    2. 使用するコネクションをクリックします。
    3. コネクションが実行するアクションを選択します。
    4. ラベルが付いたフィールドにデータを入力して、アクションを設定します。
    5. Next をクリックします。

    フローに必要なコネクションをすべて追加してから、続行します。

  3. このオペレーションフローでコネクション間のデータを処理するには、以下を行います。

    1. フロービジュアライゼーションで、ステップを追加する場所にあるプラス記号をクリックします。
    2. 追加するステップをクリックします。
    3. ラベル付が付いたフィールドにデータを入力して、ステップを設定します。
    4. Next をクリックします。

      ヘルプが必要な場合は コネクション間のステップの追加 を参照してください。

    コネクションの間のデータを処理する別のステップを追加する場合は、この手順のサブセットを繰り返します。

  4. データを次のコネクションのフィールドにマップします。

    1. フロービジュアライゼーションで、コネクションが受信データを処理できないことを示す、データタイプ不一致の data mismatch アイコンを確認します。ここでは、データマッパーステップを追加する必要があります。
    2. フロービジュアライゼーションの各データ不一致アイコンに対して以下を行います。

      1. そのステップの直前にあるプラスマークをクリックします。
      2. Data Mapper をクリックします。
      3. 必要なマッピングを定義します。ヘルプが必要な場合は インテグレーションデータを次のコネクションのフィールドにマッピング を参照してください。
      4. Done をクリックして、データマッパーステップをフローに追加します。
  5. フロービジュアライゼーションの、Provided API Return Path ステップで Configure をクリックします。

    すべての API プロバイダーインテグレーションは、オペレーションフローの実行をトリガーした REST API の呼び出し元に応答を送信することで、各オペレーションフローを終了します。応答には、オペレーションのフローを終了する Provided API Return Path ステップのに設定した戻りコードの 1 つが含まれます。以下のように、Return Path ステップを設定します。

    1. Return Code フィールドの Default Response で、Fuse Online に表示されるデフォルトの応答を指定するか、下向きのキャレットをクリックしてスクロールし、希望のデフォルト応答を選択します。オペレーションフローを実行しても設定されたエラー応答がどれも返されなかった場合、フローはこの応答を送信します。通常、デフォルト応答の戻りコードはオペレーションに成功したことを意味します。
    2. 返されたメッセージのボディー部にエラーメッセージが含まれるようにするかどうかを Error Handling に指定します。

      通常、開発中はエラーメッセージを返すようにします。しかし、実稼働では機密情報が含まれる場合にエラーメッセージを非表示にする場合があります。エラーメッセージは、responseCodecategorymessage、および error 要素が含まれる JSON 形式の文字列です。例を以下に示します。

         {
            responseCode: 404,
            category:  "ENTITY_NOT_FOUND_ERROR",
            message: "SQL SELECT did not SELECT any records"
            error: SYNDESIS_CONNECTION_ERROR
          }

      開発中、最も確実にエラーの発生を確認する方法は、呼び出し元への応答の HTTP_RESPONSE STATUS ヘッダーをチェックすることです。インテグレーション Pod のログで INFO メッセージを確認することもできます。インテグレーションの Activity ログには成功した交換が記録され、エラーは Activity ログに常に記録されるとは限りません。

    3. Error Response Codes には、フローのコネクションが返す可能性がある各エラーのエントリーが表示されます。エラーごとに、デフォルトの戻りコードである 200 All is good を指定するか、クリックして別の HTTP ステータスの戻りコードを選択します。

      選択可能な戻りコードは、このフローで実行されるオペレーションのために OpenAPI ドキュメントで定義される戻りコードです。必要な戻りコードが Fuse Online に表示されない場合、OpenAPI ドキュメントを編集して追加できます。

      これを行うには、右上の View/Edit API Definition をクリックします。必要に応じて OpenAPI ドキュメントを編集します。編集し終わったら、OpenAPI ドキュメントを保存します。Fuse Online が Provided API Return Path の編集に戻り、保存した変更が反映されます。

    4. Next をクリックし、リターンパスの設定を完了します。
  6. このフローに、必要なコネクションとステップがすべてあり、データの不一致アイコンがない場合や、現時点でフローを編集しない場合は、以下の 1 つを行います。

    • Publish: インテグレーションの実行を開始するには、右上の Publish をクリックします。これにより、インテグレーションがビルドされ、REST API サービスが OpenShift にデプロイされます。さらにインテグレーションが実行できるようになります。オペレーションフローの作成を完了するときやオペレーションフローを編集するときに、インテグレーションをパブリッシュできます。
    • Save: オペレーションのリストを表示するには、右上の Save をクリックします。

この手順を繰り返して、別のオペレーションフローを編集します。

API プロバイダーインテグレーションのテスト

  • 以下のプラットフォームの 1 つで稼働している API プロバイダーインテグレーションのテスト

    • OpenShift Online
    • OpenShift Dedicated
    • API 検出が無効になっている 場合の OpenShift Container Platform

    curl ユーティリティーを使用すると、インテグレーションが想定どおりに動作していることを確認できます。curl コマンドに、API プロバイダーインテグレーションのパブリッシュ後に Fuse Online に表示される外部 URL を指定します。この例については API プロバイダークイックスタートインテグレーションの例のテスト を参照してください。

  • API 検出が有効になっている 場合の OpenShift Container Platform で稼働している API プロバイダーインテグレーションのテスト

    Red Hat 3scale は API プロバイダーインテグレーションをパブリッシュします。インテグレーションをテストするには、3scale ダッシュボードを開き、インテグレーションの URL を取得します。

    たとえば、Red Hat 3scale でインテグレーションの API へのアクセスを制御したくない場合や、Fuse Online で API プロバイダーをテストしたい場合は、API プロバイダーインテグレーションの検出を無効にできます。検出を無効にすると、インテグレーションが Fuse Online によって再パブリッシュされ、インテグレーションの実行を呼び出しおよびテストする外部 URL が提供されます。これには、Fuse Online でインテグレーションの概要ページに移動します。このページの Disable discovery をクリックします。Fuse Online によってインテグレーションが再パブリッシュされ、インテグレーションの URL が提供されます。インテグレーションのテスト方法の例は、API プロバイダークイックスタートインテグレーションの例のテスト を参照してください。テスト後に、API プロバイダーインテグレーションの検出を再度有効にすると、3scale でパブリッシュできるようになります。

    各 API プロバイダーインテグレーションの検出を有効または無効にすることができます。