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. Chat スペースが変更されます。たとえば、スペースに新しいメッセージが投稿された場合などです。
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 ドライブのイベントをサブスクライブする
• 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 メッセージの識別子。

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

関連トピック

• Google Workspace Events API のスコープを選択する
• Google Workspace サブスクリプションを作成する