Apigee Integration と Pub/Sub 接続を使ってみる

このチュートリアルでは、統合とコネクタを使用して、Cloud Pub/Sub メッセージのパブリッシュをトリガーするサンプル統合を作成する方法について説明します。このチュートリアルは、Apigee Integration に関する実践的な知識があることを前提としています。

この例では、API エンドポイントを呼び出すと、Cloud Pub/Sub トピックへのメッセージの公開がトリガーされます。以下の手順では、統合を正常に実施するために必要な API トリガーと Cloud Pub/Sub 接続を構成する方法について説明します。

始める前に

このチュートリアルを開始する前に、Google Cloud のログイン認証情報と組織の詳細を確認してください。この情報は、コネクタ UI にアクセスする際に必要になります。Apigee Integration デザイナー内のコネクタタスクにアクセスするには、Apigee 認証情報が必要です。その他の前提条件の手順は次のとおりです。

接続を初めて作成する場合は、次の手順を完了します。
注: この手順は、Apigee Integration アドオンおよび Connector アドオンを Apigee で初めて有効にする場合にのみ必要です。
1. 新しい Apigee インスタンスを作成します。新しい Apigee インスタンスは、プロビジョニング UI でプロビジョニングできます。
  コネクタをサポートするリージョンの一覧については、コネクタをサポートするリージョンをご覧ください。
2. Apigee Integration とコネクタの機能に Apigee サブスクリプションの利用資格が付与されていることを確認します。
3. 次のコマンドを使用して、Apigee Integration とコネクタの機能を有効にします。
```
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H \
"content-type:application/json" \
"https://apigee.googleapis.com/v1/organizations/PROJECT_ID:setAddons" -XPOST \
-d '{"addonsConfig": {"integrationConfig": {"enabled": true}, "connectorsPlatformConfig": {"enabled": true}}}'
```
  警告: アドオンコマンドを実行すると、既存のアドオンが上書きされます。既存のアドオンがある場合は、アドオンコマンドに追加します。そうしないと、Apigee Integration とコネクタを有効にするコマンドにより、既存の組織内の他のアドオンがすべて無効になります。アドオンが無効になっている場合、Apigee はアドオン（機能）の構成をすべて削除します。たとえば、統合アドオンを無効にすると、すべての統合が削除されます。
4. サービスアカウントがない場合は、サービスアカウントを作成します。
  サービスアカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスして認証を受ける必要がある人間以外のユーザーを表します。サービスアカウントがない場合は、サービスアカウントを作成する必要があります。詳細については、サービスアカウントを作成するをご覧ください。
統合で使用する Pub/Sub 接続を作成する前に、次のことを行ってください。
- Cloud Pub/Sub のクイックスタート: コンソールの使用で説明されている手順に沿って Pub/Sub トピックを作成し、サブスクリプションを追加します。
- Pub/Sub トピックに公開する権限を付与します。たとえば、roles/pubsub.publisher ロールを使用してトピックに公開できます。Pub/Sub ロールの詳細については、アクセス制御をご覧ください。
- サービスアカウントのキーを生成します。JSON キーファイルは、後の手順で Pub/Sub 接続を構成するために使用されます。

必要なサービスを有効にする

コネクタでは、次の Google サービスを有効にする必要があります。

名前	タイトル
`apigee.googleapis.com`	Apigee API
`secretmanager.googleapis.com`	Secret Manager API
`connectors.googleapis.com`	Connectors API

以前にプロジェクトでこうしたサービスを有効にしていない場合は、[接続の作成] ページで接続を作成するときに有効にするよう求められます。

Pub/Sub 接続を作成する

接続を構成するには:

Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。
[接続] ページに移動
[+ 新規作成] をクリックして [接続を作成] ページを開きます。
接続を構成します。
1. [接続を作成] セクションで、次の操作を行います。
  - Connector: 使用可能なコネクタのプルダウンリストから [Cloud Pub/Sub] を選択します。
  - Connector version: 使用可能なバージョンのプルダウンリストからコネクタのバージョンを選択します。
  - [接続名] フィールドに、接続インスタンスの名前を入力します。
    接続名は次の条件を満たす必要があります。
    - 接続名には英字、数字、ハイフンを使用できます。
    - 英字は小文字のみを使用できます。
    - 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
    - 接続名は 63 文字以内で指定してください。
  - 必要に応じて、接続インスタンスの説明を入力します。
  - サービスアカウント: 必要なロールを持つサービスアカウントを選択します。
  - プロジェクト ID: Pubsub インスタンスが存在する Google Cloud プロジェクトの ID。
  - トピック ID: メッセージの公開先となるトピックの名前。
  - 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
  - [次へ] をクリックします。
2. ロケーション: 接続のロケーションを選択します。
  - [リージョン] プルダウンリストから、Apigee を使用できるロケーションを選択します。
    コネクタをサポートしているリージョンは次のとおりです。
    サポートされているすべてのリージョンのリストについては、ロケーションをご覧ください。
  - [次へ] をクリックします。
3. 認証: Cloud Pub/Sub 接続でサポートされている認証タイプ:
  - AUTH_TYPE_UNSPECIFIED
  使用する認証に基づいて詳細を入力します。
  - AUTH_TYPE_UNSPECIFIED
4. [次へ] をクリックします。
5. 確認: 接続と認証の詳細を確認します。
[作成] をクリックします。

新しい統合を作成する

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

Apigee UI に移動して、接続を作成したプロジェクトにログインします。
[Develop] > [Integrations] の順にクリックします。
[CREATE NEW] をクリックします。
[統合を作成] ダイアログで名前と説明を入力します。
注: 統合名は次の要件を満たす必要があります。
- 名前の先頭と末尾は英字または数字にする必要があります。
- 名前には、1 つの行にスペースや複数のダッシュやアンダースコアを含めることはできません。
[Create] をクリックして統合デザイナーを開きます。

API トリガーを追加する

統合を構成する一連のタスクを開始するには、トリガーが必要です。使用可能な任意のトリガーを使用して統合を開始できます。このチュートリアルでは、API トリガーを使用して統合の実行を直接呼び出します。

新規または既存の統合に API トリガーを追加する手順は次のとおりです。

統合デザイナーで [+ Add a task/trigger] をクリックして、タスクとトリガー選択ダイアログを表示します。
[Triggers] をクリックして、使用可能なトリガーを表示します。
API trigger 要素をデザイナーにドラッグします。

このトリガーに必要な構成はありません。API トリガー ID を表示するには、統合デザイナーで API trigger 要素をクリックします。構成パネルにトリガー ID が表示されます。これは、api_trigger/TRIGGER_NAME の形式で自動生成された ID です。

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

タスクは、変数を入力として受け取り、出力として変数を生成する、実行可能な一連のステップです。トリガーと同様、統合では任意の使用可能なタスクが使用できます。

このチュートリアルでは、コネクタタスクを使用します。タスクの構成の詳細は、次の手順で説明します。

Pub/Sub 接続を使用してコネクタタスクを構成する

Pub/Sub 接続を使用するように Apigee Integration でコネクタタスクを構成するには:

Apigee UI にアクセスしてログインします。
UI の左上にあるプルダウンメニューから組織を選択します。
[Develop] > [Integrations] の順にクリックします。
[Integrations] リストから編集する統合を検索または選択し、クリックして統合デザイナーを開きます。
[+Add a task/trigger] > [Tasks] の順にクリックして、使用可能なタスクのリストを表示します。
Connectors 要素を統合デザイナーにドラッグします。
デザイナーで [Connectors] タスク要素をクリックして、[Connectors] タスク構成ペインを表示します。
必要に応じ、[] をクリックしてタスク名を編集します。これにより、タスク名を汎用の「Connectors」から、統合に意味のある名前に変更できます。
[Configuration] セクションの [Configuration] タブで、[Configure task] ボタンをクリックして [Configure connector task] ペインを開きます

[Connection] 列で、使用可能な接続のリストから、前の手順で作成した Pub/Sub 接続を選択します。
接続を選択すると、[Type] 列が表示されます。この例では、使用可能なアクションのリストから [Actions] を選択し、[publishMessage] を選択します。
- エンティティは、接続されているアプリケーションまたはサービスのオブジェクト、あるいはプロパティのコレクションと考えることができ、コネクタインターフェースを介して統合に公開できます。Pub/Sub 接続はエンティティを公開しません。
- アクションは、コネクタインターフェースを介して統合で使用できる最初のクラス関数です。関数は接続されているアプリケーションまたはサービスで定義され、1 つまたは複数のエンティティに対して行うことができる変更または一連の変更を定義します。Pub/Sub 接続には、使用可能なアクションが 1 つ存在します。
[Done] をクリックして接続の構成を完了し、ペインを閉じます。

Pub/Sub 接続の [Connectors] タスク構成ペインには、接続で使用するために前の手順で選択したエンティティとオペレーションまたはアクションによって自動的に生成されたタスク入力変数およびタスク出力変数も表示されます。これらの変数には、現在の統合で構成された後続のタスクまたは条件への入力としてアクセスできます。タスクの入力を構成するには:
1. [Connector input payload] の変数ピルをクリックし、[Configure Variable] ペインを開きます。
2. [Default Value] フィールドに「{"message": "test message from integration platform"}」というテキストを入力します。
3. [Use as an input to integration] チェックボックスをオンにします。
4. [Save] をクリックします。
タスクのエラーを処理するさまざまな再試行戦略を構成できます。再試行戦略では、エラー時にタスクを再実行する方法を指定できます。詳細については、エラー処理の方式をご覧ください。
API trigger 要素上のコントロールポイントにカーソルを合わせて、API trigger 要素から Connectors 要素へのエッジ接続を追加し、線をクリックして Connectors タスク要素上のコントロールポイントにドラッグします。コントロールポイントとエッジの線が黄色に変わります。エッジは、API トリガータスクからコネクタタスクへの制御のフローを示します。

統合をテストする

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

統合デザイナーのツールバーで、[Publish] ボタンをクリックします。
[Test] をクリックして統合をトリガーし、実行します。[Test Integration] ウィンドウが開き、前の手順で設定した入力変数（メッセージ）が表示されます。必要に応じて、入力変数をここで変更できます。
[Test Integration] をクリックします。
成功すると、[Test Integration] ウィンドウに、統合の入力入出力変数のペイロードの値と、成功メッセージが表示されます。
[Close] をクリックして [Test Integration] ウィンドウを閉じます。

統合が成功したことを確認するには:

[Pub/Sub] ページに移動します。
Pub/Sub に移動
Pub/Sub トピックを選択してから、[メッセージを表示する] をクリックして、統合によって送信されたメッセージの受信を確認します。
注: メッセージが表示されるまでに数分かかる場合があります。
Apigee Integration ログを調べて、特定の統合のステータスを表示します。ログを表示するには:
1. 統合デザイナーのツールバーで、[Logs] をクリックします。
2. [Execution Logs] ページでは、統合の実行の試行ごとに関する詳細を確認できます。各エントリには、以下のような実行の試行の詳細が含まれます。
  - 統合名
  - 実行 ID
  - ステータス
  - 開始時刻
  - 期間
  - 統合 ID
  - トリガー ID
3. 実行された統合の横にある展開の矢印（>）をクリックすると、展開された統合のタスクと変数のリストと、タスクのステータスと変数のペイロードが表示されます。

これでApigee Integration で Pub/Sub 接続が作成され、正常にテストされました。

次のステップ

Apigee でサポートされているコネクタのリストを参照する。
接続の作成方法と管理方法を確認する。