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

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

Google Workspace のイベントは、Google Workspace のリソースに対する変更（リソースの作成、更新、削除など）を表します。 Google Workspace Events API を使用して Google Workspace リソースに登録し、関連するイベントを受信します。

アプリがイベントを受信する仕組み

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

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

1. Chat アプリが Google 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 リソースの変更（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 イベントをご覧ください。

イベントタイプ

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

通知エンドポイント

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

ペイロード オプション

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

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

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

詳細については、次のリソースをご覧ください。

• Chat イベントに登録する
• ドライブ イベントに登録する
• Meet イベントに登録する

Google Workspace イベントの構造

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

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

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

CloudEvent 属性

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

イベントデータ

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

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

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

イベントデータのこれらのオプションは、サブスクリプションの 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 サブスクリプションを作成する