このページでは、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 アプリにイベントを配信する方法を示します。
- Chat アプリが Chat スペースに登録されます。
- Chat スペースが変更されます。たとえば、スペースに新しいメッセージが投稿されたときなどです。
- Chat は、サブスクリプションの通知エンドポイントとして機能する
Google Cloud Pub/Sub のトピックにイベントを配信します。このイベントには、変更内容に関するデータが含まれています。たとえば、新しいメッセージに関するイベントの場合、そのイベントには作成された
Message
リソースの詳細が含まれます。 - 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 スペース |
特定のスペースに登録するには:
ユーザーがメンバーになっているすべてのスペースに登録するには:
|
詳しくは、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 Workspace のイベントの構造
Google Workspace のイベントは、イベントデータを記述する業界標準の CloudEvents 仕様に準拠しています。Google Workspace のイベントには次のものが含まれます。
次のセクションでは、Google Workspace イベントの属性とデータの構造について説明します。
CloudEvent の属性
Google Workspace イベントには、次の必須の CloudEvents 属性が含まれています。
属性 | 説明 | 例 |
---|---|---|
|
イベントで渡されたデータの型。 |
|
|
CloudEvent の識別子。 |
|
|
イベントのソース。Google Workspace イベントの場合は、サブスクリプションの完全なリソース名です。 |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
このイベントに使用される CloudEvents 仕様のバージョン。 |
|
|
イベントが発生した Google Workspace リソース。 |
|
|
イベント発生時のタイムスタンプ(RFC 3339 形式)。 |
|
|
Google Workspace イベントの種類。 |
|
イベントデータ
イベントデータは、サブスクリプションのターゲット リソース(ターゲット リソースの子リソースなど)に対する変更を表すペイロードです。サブスクリプションでは、変更されたリソースに関するデータをペイロードに含めるか、変更されたリソースの名前のみを含めるかを指定できます。
たとえば、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 サブスクリプションを作成する