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 リソースのサブスクリプションを作成します。

図 1. Google Workspace Events API が Chat アプリにイベントを配信する方法の例。

次の例では、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 Chat スペース	特定のスペースに登録するには: //chat.googleapis.com/spaces/SPACE_ID ユーザーがメンバーになっているすべてのスペースに登録するには: //chat.googleapis.com/spaces/-	メッセージ メンバーシップ リアクション 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 リソースを含むペイロードが含まれます。

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

注: リソースデータを含められるのは Chat のイベントのみです。

• リソースデータを含める: 変更されたリソースの一部またはすべてのフィールドが含まれます。リソースデータを含める場合、サブスクリプション期間は最大 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 サブスクリプションを作成する