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（推奨）または pull を使用して push できます。

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 ドキュメントに移動して、[試してみる] をクリックします。
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 Functions に送信し、Cloud Logging にログを記録します。

チャネルサービス通知の Cloud Functionsへの push

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

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

Google Cloud コンソールの Cloud Functions セクションに移動します。Cloud 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 Functions の関数がデプロイされている間、次の手順に進みます。

ステップ 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 Functions 関数のトリガー 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 Functions の関数を削除する
サブスクリプションを削除する

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

次のステップ

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

イベントリファレンス

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

API リファレンス

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

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

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

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

push エンドポイントのベストプラクティス:

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

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

イベントフィルタリング

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

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