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 がサブスクリプションを通じてアプリにイベントを配信する仕組みは次のとおりです。

1. アプリが、Google Chat スペースなどの Google Workspace アプリケーションのリソースをサブスクライブしている。
2. 登録しているリソースが変更される。
3. Google Workspace アプリケーションは、Google Workspace サブスクリプションの通知エンドポイントとして機能する Google Cloud Pub/Sub のトピックにイベントを配信します。このイベントには、リソースの変更点に関するデータが含まれています。
4. アプリは、イベントを含む 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 Chat スペース	//chat.googleapis.com/spaces/SPACE_ID	メッセージ メンバーシップ リアクション Space 詳しくは、Google Chat イベントに登録するをご覧ください。	サブスクリプションを承認する Google Chat ユーザーは、Google Workspace または Google アカウントを使用してスペースのメンバーである必要があります。
Google Chat ユーザー	//cloudidentity.googleapis.com/users/USER_ID	メンバーシップ 詳しくは、Google Chat イベントに登録するをご覧ください。	定期購入は、定期購入を承認したユーザーに関するイベントのみを受け取ります。ユーザーが他のユーザーの代理で定期購入を承認することはできません。
Google Meet
Google Meet 会議スペース	//meet.googleapis.com/spaces/SPACE_ID	コンファレンス 参加者セッション 録画 成績証明 詳しくは、Google Meet のイベントに登録するをご覧ください。
Google Meet ユーザー	//cloudidentity.googleapis.com/users/USER_ID	コンファレンス 参加者セッション 録画 成績証明 詳しくは、Google Meet のイベントに登録するをご覧ください。	サブスクリプションは、ユーザーが次のいずれかに該当する会議スペースに関するイベントを受信します。 会議スペースのオーナー。 会議スペースに関連付けられている Google カレンダーの予定の主催者。

Google Workspace イベントの構造

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

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

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

CloudEvent の属性

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

属性	説明	例
datacontenttype	イベントで渡されたデータの種類。	application/json
id	CloudEvent の識別子。	spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO
source	イベントのソース。Google Workspace イベントの場合、これはサブスクリプションの完全なリソース名です。	//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
specversion	このイベントに使用された CloudEvents 仕様のバージョン。	1.0
subject	イベントが発生した Google Workspace リソース。	//chat.googleapis.com/spaces/AAAABBBBBBB
time	イベントが発生したときのタイムスタンプ（RFC 3339 形式）。	2023-09-07T21:37:36.260127Z
type	Google Workspace イベントの種類。	google.workspace.chat.message.v1.created

イベントデータ

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

たとえば、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 Chat のイベントに登録する
• Google Workspace サブスクリプションのライフサイクル イベント
• Google Workspace Events API スコープを選択する
• Google Workspace サブスクリプションを作成する