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 プロジェクトで課金が有効になっていることを確認します。

サービスアカウントを作成します。

Google Cloud コンソールで [サービスアカウントの作成] ページに移動します。
[サービスアカウントの作成] に移動
プロジェクトを選択します。
[サービスアカウント名] フィールドに名前を入力します。Google Cloud コンソールでは、この名前に基づいて [サービスアカウント ID] フィールドに値が設定されます。

[サービスアカウントの説明] フィールドに説明を入力します。例: Service account for quickstart
[作成して続行] をクリックします。
サービスアカウントに次のロールを付与します: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

ロールを付与するには、[ロールを選択] リストを見つけてロールを選択します。

追加のロールを付与するには、 [別のロールを追加] をクリックして各ロールを追加します。

注: [ロール] フィールドは、サービスアカウントがプロジェクト内のどのリソースにアクセスできるかに影響します。これらのロールは後で取り消すことも、追加のロールを付与することもできます。本番環境では、オーナー、編集者、閲覧者のロールを付与しないでください。代わりに、ニーズに合わせて事前定義ロールまたはカスタムロールを付与します。
[続行] をクリックします。
[完了] をクリックして、サービスアカウントの作成を完了します。

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

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

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

サービスアカウントを作成します。

Google Cloud コンソールで [サービスアカウントの作成] ページに移動します。
[サービスアカウントの作成] に移動
プロジェクトを選択します。
[サービスアカウント名] フィールドに名前を入力します。Google Cloud コンソールでは、この名前に基づいて [サービスアカウント ID] フィールドに値が設定されます。

[サービスアカウントの説明] フィールドに説明を入力します。例: Service account for quickstart
[作成して続行] をクリックします。
サービスアカウントに次のロールを付与します: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

ロールを付与するには、[ロールを選択] リストを見つけてロールを選択します。

追加のロールを付与するには、 [別のロールを追加] をクリックして各ロールを追加します。

注: [ロール] フィールドは、サービスアカウントがプロジェクト内のどのリソースにアクセスできるかに影響します。これらのロールは後で取り消すことも、追加のロールを付与することもできます。本番環境では、オーナー、編集者、閲覧者のロールを付与しないでください。代わりに、ニーズに合わせて事前定義ロールまたはカスタムロールを付与します。
[続行] をクリックします。
[完了] をクリックして、サービスアカウントの作成を完了します。

環境を準備する

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"
```

統合フローのサンプル

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

統合を公開する

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

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

統合をテストする

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

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

統合エディタのツールバーで、 [テスト] をクリックします。
[Test 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 で作成した接続を削除します。

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