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 つの手順で構成されます。

  1. Pub/Sub API を有効にして、サービス アカウントを準備します。

  2. Pub/Sub トピックを作成します。このトピックはチャネル サービスが所有し、サブスクリプションを作成できるサービス アカウントを指定します。

  3. 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 メソッドを使用する必要があります。このメソッドは、サービス アカウントのメールアドレスをパラメータとして受け取ります。この方法で承認されたサービス アカウントのみが、新しいトピックにサブスクライブできます。

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

次のような 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 の関数を作成します。

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

    1. 任意の Node.js ランタイムを選択する
    2. [エントリ ポイント] を log に変更します。
    3. 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 ツールを使用します。

  1. Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] アイコンをクリックします。

  2. シェルの準備ができたら、次のコマンドを実行します。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
    
  3. シェルでサービス アカウントを有効にします。

    gcloud iam service-accounts keys create sa-keys.json \
        --iam-account=$SERVICE_ACCOUNT
    gcloud auth activate-service-account --key-file=sa-keys.json
    
  4. サブスクリプションを作成します。

    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 コンソールを使用しますが、これらの手順はプログラムで実行できます。手順は次のとおりです。

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 のすべてのシート変更を追跡できます。