API リクエストのフルフィルメント

このチュートリアルでは、Application Integration を使用して Ingress API リクエストの情報をルーティングおよびフェッチする方法のユースケースについて説明します。

概要

このチュートリアルでは、顧客情報を取得するための API リクエストを受信する API トリガーとの統合を作成します。API リクエストのロケーションに応じて、統合では MySQL データベースまたは Oracle データベースのいずれかから顧客の詳細情報を取得します。

API フルフィルメントの図

目標

このチュートリアルでは、統合で以下のタスクを行う方法について説明します。

API トリガーを追加する
MySQL 接続と Oracle 接続用のコネクタタスクを追加して構成する。
API ペイロードを抽出してマッピングするためのデータマッピングタスクを追加して構成します。

費用

このチュートリアルでは、Google Cloud の次の課金対象のコンポーネントを使用します。

このチュートリアルの手順は、リソース使用量が Google Cloud の Always Free 階層の制限内に収まるように設計されています。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Create a service account:

In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

To grant a role, find the Select a role list, then select the role.

To grant additional roles, click Add another role and add each additional role.

Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue.
Click Done to finish creating the service account.

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Create a service account:

In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

To grant a role, find the Select a role list, then select the role.

To grant additional roles, click Add another role and add each additional role.

Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue.
Click Done to finish creating the service account.

環境を準備する

MySQL データベースを設定する

MySQL サーバーに接続し、このチュートリアルで使用するデータベースとテーブルを作成します。このチュートリアルでは、Customers という名前のテーブルと次の行を含むデータベースを使用します。

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Alex          | test-01@test.com   | New York         |
  |           2 | Dana          | test-02@test.com   | Seattle          |
  +-------------+---------------+--------------------+------------------+

MySQL データベースの作成と使用については、MySQL のドキュメントをご覧ください。

Oracle データベースを設定する

Oracle データベースに接続し、このチュートリアルで使用するテーブルを作成します。このチュートリアルでは、Customers という名前の SQL テーブルと次の行を含むデータベースを使用します。

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Amal          | test-01@test.com   | Delhi            |
  |           2 | Hao           | test-02@test.com   | Beijing          |
  +-------------+---------------+--------------------+------------------+

Oracle データベースの作成と使用については、Oracle のドキュメントをご覧ください。

接続を設定

このチュートリアルでは、Integration Connectors で次の接続を構成する必要があります。

ヒント: us-central1(lowa) リージョンでは以下の接続を作成することをおすすめします。

MySQL 接続: Integration Connectors で MySQL 接続を構成して、Customer テーブルエンティティを取得します。MySQL コネクタの構成については、MySQL コネクタをご覧ください。
Oracle DB 接続: Integration Connectors で Oracle DB 接続を構成して、Customer テーブルエンティティを取得します。MySQL コネクタの構成については、Oracle DB コネクタをご覧ください。

統合を作成する

新しい統合を作成するには、次の手順を行います。

Google Cloud コンソールで [Application Integration] ページに移動します。
Application Integration に移動
ナビゲーションメニューで [統合] をクリックします。[Integrations List] ページが表示されます。
[add_box 統合を作成] をクリックし、[統合を作成] ページで次の情報を入力します。
1. 連携名: 「api_fulfilment」と入力します。
2. 説明: 「Demo integration created for tutorial」と入力します。
3. リージョン: サポートされているリージョンのリストから us-central1 を選択します。
4. [作成] をクリックして統合エディタを開きます。

統合トリガーを設定する

統合が正常に作成されたら、特定されたイベントの統合を呼び出す統合トリガーを追加して構成できます。

このチュートリアルでは、API トリガーを使用して、新しい API リクエストごとに統合を呼び出します。api_fulfilment 統合で API トリガーを追加して構成するには、次の操作を行います。

統合エディタで [トリガー] をクリックし、使用可能なトリガーのリストを表示します。
統合エディタで、[API トリガー] 要素をクリックして配置します。
Application Integration では、トリガーの [ラベル]、[トリガー名]、[トリガー ID] が自動的に入力されます。[トリガー ID] は、api_trigger/TRIGGER_NAME の形式で自動生成された ID であり、API リクエストで使用されます。

このトリガーに必要な構成はありません。

統合変数を作成する

統合変数は、プログラミング言語で使用される変数と似ています。統合の実行中に、変数内のデータの読み取りと書き込みを行うことができます。このチュートリアルに必要な変数を作成するには、次の操作を行います。

デザイナーナビゲーションバーの（切り替えパネル）をクリックして、[変数] ペインを表示します。

[+ 作成] をクリックして、次の統合変数を作成します。

変数名	データ型	変数タイプ
`location`	`STRING`	統合への入力
`customer_id`	`STRING`	統合への入力
`customer_record`	`JSON`	統合からの出力

MySQL データベースから顧客データを取得する

Ingress API リクエストが US ロケーションから送信された場合は、以下の手順で MySQL データベースから顧客データを取得します。

MySQL データベースに接続する

以下の手順で、Connectors タスクを追加して構成し、MySQL 顧客テーブルから顧客情報を取得します。

統合エディタで [タスク] をクリックし、使用可能なタスクのリストを表示します。
統合エディタで [Connectors] 要素をクリックして配置します。
デザイナーで [Connectors] タスク要素を選択して、[Connectors] タスク構成ペインを表示します。
[] をクリックし、Connectors ラベルの名前を Fetch MySQL Data に変更します。
[コネクタを設定する] をクリックします。
[Connectors Task Editor] ページで、次の操作を行います。
1. [Select connection] で、us-central1 リージョンを選択します。
2. 使用可能な接続のリストから、Salesforce 接続を選択します。
3. [Next] をクリックします。
4. [タイプ] で [エンティティ] を選択します。
5. [Set entities/actions] で使用可能なエンティティのリストから [顧客] を選択し、[オペレーション] として [入手] を選択します。
6. [完了] をクリックして接続の構成を完了し、ペインを閉じます。

お客様 ID を MySQL コネクタにマッピングする

Data Mapping タスクを使用して、お客様 ID を MySQL コネクタにマッピングします。統合でデータマッピングを追加して構成するには、次の操作を行います。

統合エディタで [タスク] をクリックし、使用可能なタスクのリストを表示します。
統合エディタで [Data Mapping] 要素をクリックして配置します。
デザイナーで [Data Mapping] 要素を選択して、タスク構成ペインを表示します。
[] をクリックし、Data Mapping タスクの名前を Map to MySQL に変更します。
[Open Data Mapping Editor] をクリックします。
データマッピングエディタを使用すると、使用可能な変換関数を使用して、入力変数を目的の出力変数にマッピングできます。出力は、他の統合タスクまたはトリガーの変数として使用できます。マッピング変数の詳細については、マッピングを追加するをご覧ください。
トリガー（customer_id）統合変数を自動生成されたコネクタ（entityId(Fetch MySQL Data)）入力変数にマッピングします。
マッピングが完了したら、ペインを閉じます。変更は自動的に保存されます。
Map to MySQL タスクから Fetch MySQL Data コネクタにエッジ接続を追加します。

MySQL の顧客の詳細を取得する

MySQL コネクタからお客様の詳細を取得するには、次の手順を実行します。

統合エディタで [タスク] をクリックし、使用可能なタスクのリストを表示します。
統合エディタで [Data Mapping] 要素をクリックして配置します。
デザイナーの [Data Mapping] 要素をクリックして、タスク構成ペインを表示します。
[] をクリックし、Data Mapping タスクの名前を Get MySQL data に変更します。
[Open Data Mapping Editor] をクリックします。
MySQL の connectorOutputPayload (Fetch MySQL Data) 出力変数を customer_record 統合変数にマッピングします。
マッピングが完了したら、ペインを閉じます。変更は自動的に保存されます。
Fetch MySQL Data コネクタから Get MySQL data タスクにエッジ接続を追加します。

Oracle データベースから顧客データを取得する

Ingress API リクエストが APAC ロケーションから送信された場合は、以下の手順で Oracle データベースから顧客データを取得します。

Oracle データベースに接続する

以下の手順で、Connectors タスクを追加して構成し、Oracle 顧客テーブルから顧客情報を取得します。

統合エディタで [タスク] をクリックし、使用可能なタスクのリストを表示します。
統合エディタで [Connectors] 要素をクリックして配置します。
デザイナーで [Connectors] タスク要素を選択して、[Connectors] タスク構成ペインを表示します。
[] をクリックし、Connectors ラベルの名前を Fetch Oracle Data に変更します。
[コネクタを設定する] をクリックします。
[Connectors Task Editor] ページで、次の操作を行います。
1. [Select connection] で、us-central1 リージョンを選択します。
2. 使用可能な接続のリストから、Salesforce 接続を選択します。
3. [Next] をクリックします。
4. [タイプ] で [エンティティ] を選択します。
5. [Set entities/actions] で使用可能なエンティティのリストから [顧客] を選択し、[オペレーション] として [入手] を選択します。
6. [完了] をクリックして接続の構成を完了し、ペインを閉じます。

お客様 ID を Oracle コネクタにマッピングする

統合でデータマッピングを追加して構成するには、次の操作を行います。

統合エディタで [タスク] をクリックし、使用可能なタスクのリストを表示します。
統合エディタで [Data Mapping] 要素をクリックして配置します。
デザイナーで [Data Mapping] 要素を選択して、タスク構成ペインを表示します。
[] をクリックし、Data Mapping タスクの名前を Map to Oracle に変更します。
[Open Data Mapping Editor] をクリックします。
トリガー（customer_id）統合変数を自動生成されたコネクタ（entityId(Fetch Oracle Data)）入力変数にマッピングします。
マッピングが完了したら、ペインを閉じます。変更は自動的に保存されます。
Map to Oracle タスクから Fetch Oracle Data コネクタにエッジ接続を追加します。

Oracle の顧客の詳細を取得する

Oracle コネクタから顧客の詳細を取得するには、次の手順を実行します。

統合エディタで [タスク] をクリックし、使用可能なタスクのリストを表示します。
統合エディタで [Data Mapping] 要素をクリックして配置します。
デザイナーの [Data Mapping] 要素をクリックして、タスク構成ペインを表示します。
[] をクリックし、Data Mapping タスクの名前を Get Oracle data に変更します。
[Open Data Mapping Editor] をクリックします。
Oracle の connectorOutputPayload (Fetch Oracle Data) 出力変数を customer_record 統合変数にマッピングします。
マッピングが完了したら、ペインを閉じます。変更は自動的に保存されます。
Fetch Oracle Data コネクタから Get Oracle data タスクにエッジ接続を追加します。

エッジ条件を追加する

エッジ条件を使用すると、統合を制御するために満たされる必要がある条件を指定して、エッジで接続されたタスクに渡すことができます。必要なタスクの追加と構成が完了したので、エッジ条件を追加して統合のフローを定義できます。

次のエッジ条件により、location 統合変数に基づいて統合のフローが制御されます。

次のエッジ条件で、API トリガーから Map to MySQL タスクにエッジ接続を追加します。
```
  $location$ = "US"
```
次のエッジ条件で、API トリガーから Map to Oracle タスクに別のエッジ接続を追加します。
```
  $location$ = "APAC"
```

統合フローのサンプル

次の図は、このチュートリアルを使用して作成された統合のサンプルレイアウトを示しています。

統合を公開する

統合を公開するには、統合デザイナーツールバーの [公開] をクリックします。

統合が正常に公開されると、公開された統合の実行ログを表示、検査できます。ログを表示するには、[View execution logs for this integration] をクリックします。実行ログのページが表示されます。

統合をテストする

統合エディタから統合をテストする

統合エディタから統合をテストするには、次の手順を実行します。

統合エディタのツールバーで、 [テスト] をクリックします。
[テスト統合] ペインが表示されます。
統合入力変数のテスト値の入力するよう求められます。このテストの目的のために、次の操作を行います。
- customer_id: 「1」と入力します。
- ロケーション: 「APAC」と入力します。
[Test Integration] をクリックします。

統合は正常に実行され、次の顧客の値が表示されます。

{ 
  "CUSTOMER_ID": 1,
  "CUSTOMER_NAME": "Amal"
  "CUSTOMER_EMAILID": "test-01@test.com "
  "CUSTOMER_CITY": "Delhi"
}

テストの詳細については、統合をテストして公開するをご覧ください。

REST API 呼び出しを使用してテストする

統合が公開され実行されるようになったので、次の POST REST 呼び出しを使用して統合を呼び出すことができます。

URL:

https://integrations.googleapis.com/v1/projects/project-name/locations/-/integrations/api_fulfilment:execute

リクエスト本文:

{"trigger_id":"api_trigger/api_fulfilment_API_1"}

例: カスタム入力を使用して API リクエストを実行する

注: 次の例では curl を使用しています。これは、通常、Linux と macOS のオペレーティングシステムにプリインストールされています。curl を所有していない場合は、curl のリリースとダウンロードのページからダウンロードできます。

curl -v -X POST -H "Content-Type: application/json" 'https://integrations.googleapis.com/v1/projects/connectors-ip-test/locations/us-central1/integrations/api-fulfillment-integration:execute' -H "Authorization: Bearer $(gcloud auth AUTH_PROFILE)" -d  '{ "triggerId": "api_trigger/api-fulfillment-integration_API_1", "inputParameters": { "customer_id": {"string_value": 1}, "location" : {"string_value" : "US"}} }'

API は、次の JSON をすべて含む統合実行レスポンスを返します。

  { 
    "CUSTOMER_ID": 2,
    "CUSTOMER_NAME": "Dana"
    "CUSTOMER_EMAILID": "test-02@test.com "
    "CUSTOMER_CITY": "Seattle"
  }

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、統合の公開を停止して、Integration Connectors で作成した接続を削除します。

この統合の公開を停止するには、統合エディタツールバーの [公開を停止] をクリックします。詳細については、統合を削除するをご覧ください。
接続を削除する方法については、コネクタを管理するをご覧ください。