Google Workspace Events API を使用してイベントに登録する

このページでは、Google Workspace Events API の概要と、この API を使用して Google Workspace 全体のイベントに登録する方法について説明します。

Google Workspace のイベントは、Google Workspace のリソースに対する変更（リソースの作成、更新、削除など）を表します。アプリは Google Workspace リソースをサブスクライブして、関心のある関連イベントを受信できます。

アプリがイベントを受信する方法

アプリが Google Workspace イベントを受信できるようにするには、Google Workspace Events API を使用して Google Workspace リソースのサブスクリプションを作成します。

次の例は、Google Workspace Events API がサブスクリプションを通じて Google Chat アプリにイベントを配信する方法を示しています。

1. Chat アプリが Chat スペースをサブスクライブします。
2. チャット スペースが変更されます。たとえば、スペースに新しいメッセージが投稿された場合です。
3. Chat は、サブスクリプションの通知エンドポイントとして機能する Google Cloud Pub/Sub のトピックにイベントを配信します。このイベントには、変更内容に関するデータが含まれます。たとえば、新しいメッセージに関するイベントの場合、イベントには作成された Message リソースの詳細が含まれます。
4. Chat アプリは、イベントを含む Google Cloud Pub/Sub メッセージを処理し、必要に応じてアクションを実行します。

重要な用語

Google Workspace Events API で使用される一般的な用語を以下に示します。

Google Workspace のイベント

Google Workspace リソースの変更。イベントは CloudEvents 仕様を使用してフォーマットされ、サブスクリプション イベントまたはライフサイクル イベントのいずれかになります。

サブスクリプション イベント

モニタリングしている Google Workspace リソースの変更（Google Chat スペースの新しいメッセージなど）。変更されたリソースに関する詳細を指定できます。詳しくは、Google Workspace イベントの構造をご覧ください。

ライフサイクル イベント

Google Workspace サブスクリプションに関するイベント。ライフサイクル イベントは、定期購入の問題と状態を通知するため、定期購入イベントを見逃すことがなくなります。デフォルトでは、定期購入は常にライフサイクル イベントを受信します。詳しくは、Google Workspace サブスクリプションのライフサイクル イベントをご覧ください。

Google Workspace サブスクリプション

Google Workspace アプリケーションからリソースをモニタリングする名前付きエンティティ。サブスクリプションは Subscription リソースで表されます。定期購入は次の情報で定義されます。

ターゲット リソース

モニタリングする Google Workspace リソース。このリソースは、Google Workspace サブスクリプションの targetResource フィールドで表されます。各サブスクリプションでモニタリングできるリソースは 1 つだけです。Google Workspace Events API がサポートする Google Workspace リソースについては、サポートされている Google Workspace イベントをご覧ください。

イベントの種類

ターゲット リソースに関する通知を受け取る変更の種類。たとえば、Google Chat スペースを定期購読している場合は、スペースとその子リソース（メンバーシップやメッセージなど）に関するイベントを受信するかどうかを選択できます。

通知エンドポイント

Google Workspace サブスクリプションがイベントを受信するエンドポイント。Google Workspace Events API は、通知エンドポイントとして Google Cloud Pub/Sub トピックをサポートしています。Google Cloud Pub/Sub の使用方法については、Google Cloud Pub/Sub のドキュメントをご覧ください。

ペイロード オプション

変更されたリソースに関するイベントデータ。

サポートされている Google Workspace イベント

アプリが受信できるイベントは、サブスクリプションのターゲット リソースによって異なります。次の表に、使用可能なターゲット リソースごとにサポートされているイベントを示します。

詳細については、次のガイドをご覧ください。

• Google Chat のイベントに登録する
• Google Meet の予定を定期購入する

Google Workspace イベントの構造

Google Workspace イベントは、イベントデータを記述するための業界標準である CloudEvents 仕様に準拠しています。Google Workspace イベントには次のものが含まれます。

• CloudEvent の属性。
• イベントの結果として変更された Google Workspace リソースに関するデータ

次のセクションでは、Google Workspace イベントの属性とデータの構造について説明します。

CloudEvent の属性

Google Workspace イベントには、次の必須の CloudEvents 属性が含まれています。

イベントデータ

イベントデータは、サブスクリプションのターゲット リソース（ターゲット リソースの子リソースを含む）の変更を表すペイロードです。サブスクリプションで、ペイロードに変更されたリソースに関するデータを含めるか、変更されたリソースの名前のみを含めるかを指定できます。

たとえば、Chat スペースを定期購入している場合は、スペース内の新しいメッセージに関するイベントを受信できます。新しいメッセージに関するイベントの場合、イベントデータには、作成された Chat spaces.message リソースを含むペイロードが含まれます。

サブスクリプションを作成するときに、アプリが受信するイベントに含めるリソースデータの量を指定できます。

• リソースデータを含める: 変更されたリソースの一部またはすべてのフィールドが含まれます。リソースデータを含める場合、サブスクリプションの有効期間は最大 4 時間（ドメイン全体の委任を使用している場合は 24 時間）に制限されます。
• リソースデータを除外する: 変更されたリソースの名前のみが含まれます。サブスクリプションの有効期間は最大 7 日間です。イベントの詳細を取得するには、リソース名を使用してリソースをクエリします。

イベントデータのこれらのオプションは、サブスクリプションの payloadOptions フィールドに表示されます。

Google Cloud Pub/Sub メッセージとしてのイベント

Google Workspace Events API サブスクリプションは、Google Workspace イベントを受信する通知エンドポイントとして Google Cloud Pub/Sub トピックを使用します。イベントは Google Cloud Pub/Sub メッセージとしてエンコードされます。アプリは Google Cloud Pub/Sub メッセージを処理して、アクションを実行したり、イベントに応答したりできます。

次の例は、Chat スペース内の更新されたメッセージに関するイベントを含む Google Cloud Pub/Sub メッセージを示しています。

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

次のフィールドに注意してください。

• attributes: CloudEvent の属性（イベントタイプなど）。この場合、イベントはスペース内の更新されたメッセージに関するものです。
• data: 更新された spaces.message リソースの詳細を含むイベントデータ。Base64 エンコードされた文字列形式です。
• messageId: Google Cloud Pub/Sub メッセージの ID。

Google Cloud Pub/Sub メッセージで CloudEvents を指定する方法については、CloudEvents の Google Cloud Pub/Sub プロトコル バインディングをご覧ください。

関連トピック

• Google Chat のイベントに登録する
• Google Meet の予定を定期購入する
• Google Workspace サブスクリプションのライフサイクル イベント
• Google Workspace Events API のスコープを選択する
• Google Workspace サブスクリプションを作成する