Pub/Sub 通知

API 設定 Codelab を完了して Google Cloud プロジェクトを設定し、Cloud Channel API を呼び出すサービスアカウントを作成します。
この Codelab では、Test Partner Sales Console を使用することをおすすめします。
Pub/Sub のコンセプトについて十分に理解してください。

概要

Cloud Channel API は Pub/Sub を使用して、さまざまな顧客イベントと利用資格イベントに関する通知を配信します。

これは特に次の場合に役立ちます。

ご利用のシステムで Partner Sales Console で直接行われた変更（サポートチーム誰かが Google Workspace の利用資格をキャンセルするなど）を反映します。
販売パートナー経由で購入されたお客様によってトリガーされた重要なイベントを検出します。次に例を示します。
- 利用規約に同意する Google Workspace のお客様。
- ドメインの所有権を証明する Google Workspace のお客様。
- フレキシブルな利用資格でユーザーを追加している Google Workspace のお客様。
- 移行する Google Workspace のお客様。

Pub/Sub の設定は、次の 3 つの手順で構成されます。

Pub/Sub API を有効にして、サービスアカウントを準備します。
Pub/Sub トピックを作成します。このトピックはチャネルサービスが所有し、サブスクリプションを作成できるサービスアカウントを指定します。
Pub/Sub サブスクリプションを作成します。このサブスクリプションは、Webhook を使用してpush またはpull できます（推奨される方法）。

push サブスクリプションの場合、チャネルサービスによって出力されたイベントを受信する Webhook をホストします。

チャネルサービスのプッシュ通知

通知形式

次の例は、Pub/Sub 通知の例です。メッセージデータは、base64 でエンコードされた JSON 文字列として送信されます。

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

これは、デコードされたものと同じメッセージデータです。

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

ステップ 1: Pub/Sub API を有効にしてサービスアカウントを準備する

この Codelab を実行するには、次のものが必要です。

プロジェクトのサービスアカウントのメールアドレス。このアドレスは、service-account@project.iam.gserviceaccount.comのようになります。
販売パートナードメインの特権管理者アカウントへのアクセス権（Test Partner Sales Console のものを使用することをおすすめします）。
アカウント ID。これは、Partner Sales Console の設定で確認できます。

サービスアカウントを準備するには:

Google Cloud コンソールで [API ライブラリ] セクションに移動し、Pub/Sub API を有効にします。
サービスアカウントにプロジェクトの Pub/Sub IAM ロールを付与します。この Codelab コードラボでは、roles/pubsub.editor（ロール名 = 'Pub/Sub 編集者'）の付与で十分ですが、本番環境の統合では、よりきめ細かな権限を使用することができます。IAM ロールの詳細については、Pub/Sub のアクセス制御のページをご覧ください。
代わりにカスタムロールを適用する場合は、そのロールにサブスクリプションを作成する pubsub.subscriptions.create 権限を付与する必要があります。

これらのロールと権限をアカウントに適用してから、しばらく時間がかかることがあります。

ステップ 2: アカウントのトピックを作成する

Pub/Sub トピックを作成するには、accounts.register メソッドを使用する必要があります。このメソッドは、サービスアカウントのメールアドレスをパラメータとして受け取ります。この方法で承認されたサービスアカウントのみが、新しいトピックにサブスクライブできます。

accounts.register のドキュメントに移動し、[Try it!] をクリックします。
account フィールドに accounts/ACCOUNT_ID を入力し、ACCOUNT_ID をアカウント ID に置き換えます。
[リクエスト本文パラメータを追加] をクリックして serviceAccount を選択し、サービスアカウントのメールアドレスを入力します。
[実行] をクリックし、販売パートナードメインの特権管理者としてログインします。

次のような 200 のレスポンスが返されます。

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

これは、イベントが投稿される Pub/Sub トピックです。

ステップ 3: トピックをサブスクライブする

Pub/Sub トピックを作成したら、アプリケーションが変更イベントを使用する方法を設定する必要があります。この場合は、次のどちらかを行ってください。

push サブスクリプション: HTTP POST コールバックを指定します。Pub/Sub は、これを使用して新しいイベントをアプリケーションに通知します。
pull サブスクリプション: アプリケーションは定期的に HTTP 呼び出しを行い、キューに追加された変更を取得します。

この Codelab では、push を使用して、Cloud Logging に記録される Cloud Run の関数にすべてのイベントを送信します。

チャネルサービス通知の Cloud Run の関数への push

ステップ 3a: Cloud Run の関数を作成する

このステップでは、受信したメッセージをロギングする Cloud Run の関数を作成します。

Google Cloud コンソールの [Cloud Run の関数] セクションに移動します。Cloud Run functions API を有効にする必要があります。
[ファンクションを作成] をクリックします。
[構成] 画面で次の操作を行います。
1. 関数の名前を変更します。必要に応じて、別のリージョンを選択します。
2. HTTP トリガーで、[認証] を [未認証の呼び出しを許可する] に変更し、[保存] をクリックします。
3. [トリガー URL] をメモしておきます。次のステップでこれが必要になります。
4. [次へ] をクリックします。

[コード] 画面で次の操作を行います。

任意の Node.js ランタイムを選択する
[エントリポイント] を log に変更します。
index.js ファイルで、サンプルコードを次のコードに置き換えます。

exports.log = (req, res) => {
  if (req.body && req.body.message) {
    console.log(req.body);
    const message = req.body.message;
    // data is base64-encoded JSON
    const data = new Buffer.from(message.data, 'base64').toString();
    console.log(data);
  }
  res.status(200).send('OK');
};

Cloud Run の関数がデプロイされている間に、次のステップに進みます。

手順 3b: サブスクリプションを作成する

サブスクリプションを作成できるのは、チャネルサービストピックに登録されているサービスアカウント（ステップ 2 を参照）のみです。

これを行うには、サービスアカウントの認証情報を使用して Pub/Sub API を呼び出します。販売パートナードメインの特権管理者の権限を借用しないようにしてください。これは、Cloud Channel API を呼び出すときに必要になります。

この Codelab では、Cloud Shell で gcloud CLI ツールを使用します。

Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] アイコンをクリックします。
シェルの準備ができたら、次のコマンドを実行します。SERVICE_ACCOUNT の値はサービスアカウントのメールアドレスに、TOPIC はステップ 2 で作成したトピックに置き換え、PUSH_ENDPOINT は手順 3a で作成した Cloud Run の関数のトリガー URL に置き換えます。
```
SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
```

シェルでサービスアカウントを有効にします。

gcloud iam service-accounts keys create sa-keys.json \
    --iam-account=$SERVICE_ACCOUNT
gcloud auth activate-service-account --key-file=sa-keys.json

サブスクリプションを作成します。

gcloud pubsub subscriptions create channel-pubsub-test \
    --topic=$TOPIC \
    --push-endpoint=$PUSH_ENDPOINT

サブスクリプションが設定されていることを確認するには、[Pub/Sub サブスクリプション] セクションに移動します。

データを生成する

前の手順を完了すると、データを受信できるようになります。

最も簡単な方法は、Partner Sales Console 顧客を作成し、プロダクトをプロビジョニングすることです。エンドツーエンドの Workspace プロビジョニング Codelab を完了したら、サンプルコードを実行して Google Workspace を持つ顧客を作成できます。

Google Cloud コンソールで関数に移動し、[ログ] タブを開きます。次に例を示します。

Pub/Sub イベントのサンプルログ

クリーンアップ

Cloud Run の関数を削除する
サブスクリプションを削除する

サブスクライバーが残っていないトピックは、自動的にクリーンアップされます。

次のステップ

この Codelab では、チャネルサービスが Pub/Sub を活用して、リアクティブかつ大規模に統合を構築する方法を説明しました。

イベントリファレンス

チャネルサービスによって生成されるイベントのリストについては、RPC リファレンスをご覧ください。

API リファレンス

この Codelab では Google Cloud コンソールを使用しますが、これらの手順はプログラムで実行できます。手順は次のとおりです。

accounts.register を使用してトピックを作成します。
Pub/Sub API の subscriptions.create を使用して Pub/Sub サブスクリプションを作成します。
統合で使用できるその他のエンドポイントについては、accounts.listSubscribers と accounts.unregister をご覧ください。

Pub/Sub の保証とベストプラクティス

イベントとその通知の間の遅延は保証されません。同様に、通知の順序は保証されません。最後に、メッセージが複数回配信されることがあります。

プッシュエンドポイントのベストプラクティス:

メッセージの遅延、送信の順不同、複数回の送信の可能性があるため、エンドポイントはべき等とし、customers.get および entitlements.get を使用する必要があります。
push のデフォルトの Pub/Sub タイムアウトは 10 秒ですが（Pub/Sub サブスクリプションの ackDeadline を使用して増やすことが可能）、メッセージベースのアーキテクチャを使用し、エンドポイントが可能な限り迅速に応答するようにすることをおすすめします。
エンドポイントが停止している場合や 5xx エラーが返された場合、Pub/Sub は再試行します。プッシュでメッセージを受信する方法の詳細については、Pub/Sub のドキュメントをご覧ください。

pull を使用する場合は、Pub/Sub ドキュメントで pull を介してメッセージを受信する方法に関する情報をご覧ください。

イベントフィルタリング

チャネルサービスの通知には attributes が含まれているため、Pub/Sub フィルタリングを使用して特定の Pub/Sub サブスクリプションを作成することで、きめ細かいサブスクリプションを作成できます。

たとえば、attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" でフィルタリングすると、Google Workspace のすべてのシート変更を追跡できます。