API トリガーと Apigee Integration

このクイックスタートでは、Apigee Integration でサンプルの統合を作成する方法について説明します。次の手順では、完全な統合の実行に必要なトリガー、タスク、エッジ、変数、データマッピングを構成する方法を説明します。

このクイックスタートでは、公開 API からページビューの数を取得し、データを使用可能な形式に変換して、生成されたリストをメールで送信します。これらはすべて統合デザイナー内で行うことができます。

新しい統合を作成する

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

Apigee UI で、Apigee 組織を選択します。
[Develop] > [Integrations] の順にクリックします。
[Create Integration] をクリックします。
[Create Integration] ダイアログで名前と説明を入力します。
このクイックスタートでは、名前 my-test-integration と説明 Integration for quickstart を入力します。
統合のリージョンを選択します。
注: [Regions] プルダウンには、Google Cloud プロジェクトにプロビジョニングされたリージョンのみが表示されます。新しいリージョンをプロビジョニングするには、[Enable Region] をクリックします。詳細については、新しいリージョンを有効にするをご覧ください。
[Create] をクリックして統合エディタを開きます。

API トリガーを追加して構成する

統合を構成する一連のタスクを開始するには、トリガーが必要です。使用可能な任意のトリガーを使用して統合を開始できます。このクイックスタートでは、API トリガーを使用します。

API トリガーを構成する手順は次のとおりです。

統合エディタで [Triggers] をクリックし、使用可能なトリガーのリストを表示します。
統合エディタで、[API trigger] 要素をクリックして配置します。
デザイナーで [API trigger] 要素をクリックして、トリガー構成ペインを開きます。
Apigee Integration では、トリガーのラベル、トリガー名、トリガー ID が自動的に入力されます。トリガー ID は自動生成されており、値は編集できません。ただし、[Label] プロパティと [Trigger name] プロパティの値を編集することはできます。
プロパティへの変更は自動的に保存されます。

タスクを追加して構成する

タスクは、変数を入力として受け取り、出力として変数を生成する、実行可能な一連のステップです。トリガーと同様、統合では任意の使用可能なタスクが使用できます。このクイックスタートでは、REST エンドポイントの呼び出し、データマッピング、メールの送信の各タスクを使用します。各タスクの構成の詳細は、以降の手順で説明します。

REST エンドポイントの呼び出しタスクを構成する

REST エンドポイント呼び出しタスクを構成するには、次の操作を行います。

[Tasks] を選択して、使用可能なタスクのリストを表示します。
統合エディタで [Call REST Endpoint] 要素をクリックして配置します。
[API trigger] 要素からエッジ接続を [Call REST Endpoint] 要素に追加するには、[API trigger] 要素のコントロールポイントの上にカーソルを合わせてからクリックし、[Call REST Endpoint] タスク要素のコントロールポイントに線を引きます。エッジは、API トリガーから REST エンドポイント呼び出しタスクへの制御のフローを示します。
エッジは、統合の 2 つの要素間の接続です。接続は、ある要素（タスクまたはトリガー）から別の要素への制御フローの方向を示します。エッジの詳細については、エッジをご覧ください。
デザイナーで [Call REST Endpoint] 要素をクリックして、タスク構成ペインを開きます。次のプロパティ値を設定します。
- Label: このタスクのカスタム名を入力します。たとえば、「Call REST Endpoint Task」と入力します。
- Authentication: このクイックスタートでは、認証プロファイルは必要ありません。他のユースケースで認証プロファイルを使用する方法について詳しくは、Apigee Integration で認証プロファイルを作成するをご覧ください。
- Task Input: REST エンドポイントを呼び出すための詳細を入力します。ここに入力した情報は、REST エンドポイントの呼び出しタスクの入力として使用されます。次の情報を入力します。
  - Endpoint base URL: 「https://wikimedia.org/api/rest_v1/metrics/pageviews/per-article/en.wikipedia/desktop/user/Tree/monthly/20201001/20201031」と入力します。wikimedia.org の一般公開 API により、「Tree」という名前の記事に対する特定の月のページビュー数が返されます。
  - HTTP method: プルダウンリストを使用して [GET] を選択します。
- Task Output: REST エンドポイント呼び出しのレスポンスデータの出力を格納するため、Apigee Integration により、ここには次の 3 つの変数が入力されます。
  - responseHeader(Call REST Endpoint): この変数は、REST エンドポイント呼び出しタスクに関連付けられたレスポンスヘッダーのデータを保持します。変数データの型は String（STR）です。
  - responseBody(Call REST Endpoint): この変数は、REST エンドポイント呼び出しタスクに関連付けられたレスポンス本文のデータを保持します。変数データの型は String（STR）です。
  - responseStatus(Call REST Endpoint): この変数は、REST エンドポイント呼び出しタスクに関連付けられたレスポンスステータスのデータを保持します。変数データの型は String（STR）です。
- タスク構成ペインで変数名をクリックすると、各変数の詳細が表示されます。このクイックスタートでは、これらの変数のそれぞれについてデフォルト値のままにします。
- 残りのフィールドには、次のデフォルト値が含まれている必要があります。
  - Follow redirects: True
  - Task should fail on HTTP Error: False
  - Error handling strategy
    - Strategy for synchronous executions: None
    - Strategy for asynchronous executions: None
プロパティへの変更は自動的に保存されます。

データマッピングタスクを追加して構成する

データマッピング タスクを構成するには:

[Tasks] を選択して、使用可能なタスクのリストを表示します。
統合エディタで [Data Mapping] 要素をクリックして配置します。
[Call REST Endpoint] 要素から [Data Mapping] 要素にエッジ接続を追加するには、[Call REST Endpoint] 要素のコントロールポイントの上にカーソルを合わせてからクリックし、[Data Mapping] タスク要素のコントロールポイント線を引きます。エッジは、REST エンドポイント呼び出しタスクからデータマッピングタスクへの制御のフローを示します。
デザイナーの [Data Mapping] タスクをクリックして、タスクの構成ペインを開きます。
[Open Data Mapping Editor] をクリックします。
データマッピングエディタを使用すると、使用可能な変換関数を使用して、入力変数を出力変数にマッピングできます。出力は、他の統合タスクまたはトリガーの変数として使用できます。データを変数として渡す方法の詳細については、Apigee Integration で変数を使用するをご覧ください。

このクイックスタートでは、responseBody(Call REST Endpoint) を入力として使用して、マッピングを作成します。
1. responseBody 変数を [Variables] ペインから最初の [Input] 行にドラッグします。
2. responseBody 変数チップの [+ (Add a function)] をクリックして、使用可能な関数のプルダウンリストを表示します。
3. 入力関数でデータを変換するには、いくつかの関数を適用できます。
  この場合、ペイロードを JSON に変換し、次にレスポンス配列を反復処理して、メール通知に必要なプロダクト名のリストを取得できます。
  - [TO_JSON()] を選択し、responseBody 文字列を JSON に変換します。
  - responseBody 変数チップでもう一度 [+ (Add a function)] をクリックして、GET_PROPERTY() 関数を選択してチェーンします。
  - GET_PROPERTY() の入力パラメータを追加するには、[Variable or Value] をクリックし、[Value] に「items」と入力します。
    この関数は、JSON ペイロードからプロパティを抽出します。この関数のパラメータとして items プロパティに渡します。これにより、プロダクト名のみのリストが返されます。プロダクトの他の情報は含まれません。関数は次のようになります:
```
responseBody(Call REST Endpoint).TO_JSON().GET_PROPERTY(items)
```
  - 関数を削除または取り消すには、- 記号をクリックします。
4. [Output] 列の最初のフィールドをクリックして、変換されたデータの値を保持する新しい変数を作成します。次のフィールドに値を入力します。
  - Name: 「JSONList」と入力します。
  - Data Type: JSON
  - [Use as an output of integration] チェックボックスをオンにします。
  - [Create] をクリックして変数を作成し、ペインを閉じます。新しい JSONList 変数が、データマッピングエディタの左側にある [Variables] リストに表示されます。
5. マッピングが完了したら、データマッピングエディタを閉じます。変更は自動的に保存されます。

メール送信タスクを追加して構成する

メール送信タスクを構成するには:

統合エディタで [Tasks] を選択して、使用可能なタスクのリストを表示します。
統合エディタで [Send Email] 要素をクリックして配置します。
[Data Mapping] 要素から [Send Email] 要素にエッジ接続を追加するには、[Data Mapping] 要素のコントロールポイントにカーソルを合わせてからクリックし、[Send Email] タスク要素のコントロールポイントに線を引きます。エッジは、データマッピング タスクからメール送信タスクへの制御フローを示します。
デザイナーで [Send Email] 要素をクリックして、タスクの構成ペインを開きます。次のプロパティ値を設定します。
- To Recipient(s): メールアドレスを入力します。このメールアドレスを使用して、統合が正常に完了していることを確認します。
- Subject: 「Email from Apigee Integration」と入力します。
- Body in Plain Text: データマッピング タスクで前に作成した JSONList 変数を選択します。
- 残りのオプションはデフォルト構成のままにします。
プロパティへの変更は自動的に保存されます。

必要なエッジ接続を確認する

統合内の要素間にエッジ接続を追加したことを確認します。接続は、ある要素（タスクまたはトリガー）から別の要素への制御フローの方向を示します。エッジの詳細については、エッジをご覧ください。

次の図のように、完成した接続が表示されます。

クイックスタートフローを示す画像

統合をテストする

新しい統合をテストするには:

統合エディタのツールバーで、[Test] をクリックします。
[テスト統合] ペインが表示されます。
[Test Integration] をクリックします。

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

正常に完了すると、メール送信タスクで指定したメールアドレスに JSON 値を含むメールが送信されます。メールクライアントでメールの受信を確認します。

統合によって送信されるメールには、次のような本文が含まれています:

[{
   "project": "en.wikipedia",
   "article": "Tree",
   "granularity": "monthly",
   "timestamp": "2020100100",
   "access": "desktop",
   "agent": "user",
   "views": 33828.0
}]

メールの内容の確認に加え、ログを調査して、特定の統合のステータスとペイロードを確認できます。ログを表示するには:

統合エディタのツールバーで、[Logs] をクリックします。
[Execution Logs] ページでは、統合の実行の試行ごとに関する詳細を確認できます。各エントリには、以下のような実行の試行の詳細が含まれます。
- 統合名
- 実行 ID
- ステータス
- 開始時刻
- 期間
- 統合バージョン
- トリガー ID
実行された統合の横にある展開矢印（>）をクリックすると、展開された統合のタスクと変数のリストと、タスクのステータスと変数のペイロードが表示されます。