このページでは、Google Workspace Events API を使用して Google Chat アプリが登録できる Google Chat イベントについて説明します。必要なイベントの種類を決定したら、サブスクリプションを作成して、Google Chat からのイベントの受信を開始します。
イベントのサブスクライブに加えて、Chat API を呼び出してイベントをクエリすることもできます。Chat API を呼び出すことで、定期的にイベントを取得したり、サービス停止によってサブスクリプションから逃した可能性のあるイベントを確認したりできます。Chat のイベントを受信して応答する方法については、Chat のドキュメントの Google Chat のイベントを操作するをご覧ください。
サポートされている Chat ターゲット リソース
Google Workspace Events API では、次のサブスクリプションがサポートされています。
space
リソースとして表されるスペース- Cloud Identity API の
user
リソースとして表されるユーザー
サポートされているチャット イベント
Google Workspace サブスクリプションでは、Chat で次の種類の変更に関するイベントを受信できます。
- スペース内の新規、更新、削除されたメッセージ。
- メッセージに対する新規または削除されたリアクション。
- スペース内の新規、更新、削除されたメンバー。
- 登録しているスペースの変更(スペースの名前や説明の更新など)。
定期購入を作成するためのイベントタイプ
サブスクリプションを作成するときに、eventTypes[]
フィールドを使用して、受信するイベントのタイプを指定します。イベントタイプは、google.workspace.APPLICATION.RESOURCE.VERSION.ACTION
などの CloudEvents 仕様に従ってフォーマットされます。
たとえば、Chat スペースに参加したユーザーに関するイベントを受信するには、スペースをターゲット リソースとして指定し、イベントタイプを google.workspace.chat.membership.v1.created
として指定します。任意のユーザーがスペースに参加したことに関するイベントを受信するには、そのユーザーをターゲット リソースとして指定し、イベントの種類を google.workspace.chat.membership.v1.created
として指定します。イベントの仕組みについて詳しくは、Google Workspace イベントの構造をご覧ください。
次の表に、スペースへの登録とユーザーの登録でサポートされるイベントタイプを示します。イベントをトリガーする例外については、制限事項をご覧ください。
イベントの種類 | 形式 | リソースデータ | ||
---|---|---|---|---|
スペースへの登録 | ||||
メッセージが投稿されます。 |
|
|
||
メッセージが更新される。 |
|
|
||
メッセージが削除された。 |
|
|
||
リアクションが作成されます。 |
|
|
||
リアクションが削除されました。 |
|
|
||
メンバーがスペースに追加されます。 |
|
|
||
スペース内のメンバーが更新される。 |
|
|
||
メンバーがスペースから削除されます。 |
|
|
||
スペースが更新されます。 |
|
|
||
スペースは削除されます。 |
|
|
||
ユーザーのサブスクリプション | ||||
ユーザーがスペースのメンバーになります。
すべての新しいメンバーがイベントをトリガーするわけではありません。詳細については、制限事項をご覧ください。 |
|
|
||
スペースへのユーザーのメンバーシップが更新されます。 |
|
|
||
そのユーザーはスペースの直接のメンバーから削除されます。 |
|
|
バッチ イベントタイプ(出力のみ)
Chat アプリは、サブスクライブしているイベントタイプを受信するだけでなく、バッチイベントも受信する場合があります。バッチイベントは、短期間に発生する同じタイプの多数のイベントを表すイベントです。バッチイベントのペイロードには、変更されたすべてのリソースのリストが含まれます。
たとえば、ユーザーが同時に 20 人のユーザーをスペースに追加すると、Chat アプリはバッチイベント(google.workspace.chat.membership.v1.batchCreated
)を受信する可能性があります。イベント ペイロードには、ユーザーがスペースにメンバーを追加したときに作成されたすべての新しい Membership
リソースのリストが含まれます。
サブスクライブしているすべてのイベントタイプのバッチイベントを受け取るため、サブスクリプションの作成時にバッチイベントを指定する必要はありません。たとえば、新しいリアクション(google.workspace.chat.reaction.v1.created
)に登録すると、バッチ リアクション イベント(google.workspace.chat.reaction.v1.batchCreated
)を受信するように Chat アプリが自動的に構成されます。
次の表に、サブスクリプションで発生する可能性のあるバッチ イベントを示します。
バッチイベントタイプ | 形式 |
---|---|
複数のメッセージが投稿されます。 |
|
複数のメッセージが更新されました。 |
|
複数のメッセージが削除されます。 |
|
複数のリアクションが作成されます。 |
|
複数のリアクションが削除されます。 |
|
登録済みスペースに複数のメンバーが追加されたか、登録済みユーザーが複数のスペースに追加されている。 |
|
登録済みスペースまたは登録済みユーザーの複数のメンバーシップが更新されます。 |
|
登録済みスペースから複数のメンバーが削除されたか、登録済みユーザーが複数のスペースから削除されています。 |
|
スペースに複数の更新があります。 |
|
イベントデータ
このセクションでは、Chat でのイベントのイベントデータとサンプル ペイロードについて説明します。
Google Workspace サブスクリプションが Chat からイベントを受信すると、data
フィールドにそのイベントのペイロードが含まれます。このペイロードには、変更された Google Workspace リソースに関する情報が含まれています。たとえば、スペースのメンバーシップ イベントに登録している場合、これらのイベントのペイロードには、変更された spaces.membership
リソースに関する情報が含まれます。
イベント ペイロード内のリソースデータ
サブスクリプションを作成するときに、ペイロードにリソースの詳細を含めるか、リソースの名前のみを含めるかを指定できます。たとえば、Chat スペースのメンバーに関するイベントを受信する場合は、イベント ペイロードで受信するメンバーシップ リソースのフィールドを指定できます。
次の表に、Chat スペース spaces/AAAABBBBBB
のサブスクリプションの JSON ペイロードの例を示します。定期購入が受信するイベントごとに、ペイロードがイベントの data
フィールドに表示されます。
例 | イベントの種類 | JSON ペイロード |
---|---|---|
ユーザーが「Hello World」というメッセージをスペースに投稿します。 |
|
リソースデータが含まれます
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD", "sender": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "2023-09-07T21:37:36.260127Z", "text": "Hello world", "thread": { "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE" }, "space": { "name": "spaces/AAAABBBBBB" }, "argumentText": "Hello world" } } リソースデータを除く
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD" } } |
ユーザーがスペースの管理者になります。 |
|
リソースデータが含まれます
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MANAGER" } } リソースデータを除く
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } } |
ユーザーがスペースの説明を「Cymbal Labs のセールスチーム」に更新します。 | google.workspace.chat.space.v1.updated |
リソースデータが含まれます
{ "space": { "name": "spaces/AAAABBBBBB", "displayName": "Cymbal Sales", "spaceThreadingState": "THREADED_MESSAGES", "spaceType": "SPACE", "spaceDetails": { "description": "Sales team for Cymbal Labs." }, "spaceHistoryState": "HISTORY_ON" } } リソースデータを除く
{ "space": { "name": "spaces/AAAABBBBBB" } } |
2 人の Chat ユーザーが同時にスペースに追加されました。 | google.workspace.chat.membership.v1.batchCreated |
リソースデータが含まれます
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/987654321234567890", "state": "JOINED", "member": { "name": "users/987654321234567890", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } } ] } リソースデータを除く
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/98765432123456789019" } } ] } |
ユーザーがメッセージに 😊? の絵文字でリアクションします。 | google.workspace.chat.reaction.v1.created |
リソースデータが含まれます
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } } リソースデータは省略
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" } } |
ユーザーはメッセージに 😊? 絵文字 や Ω の絵文字でリアクションします。 | google.workspace.chat.reaction.v1.batchCreated |
リソースデータが含まれます
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } }, { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", "user": { "name": "users/98765431234564321", "type": "HUMAN" }, "emoji": { "unicode": "😸" } } } ] } リソースデータは省略
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" }, "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", } } ] } |
制限事項
-
ユーザーの登録の場合、ダイレクト メッセージまたは名前のないグループ チャットの新しいメンバーに関するイベント(
google.workspace.chat.membership.v1.created
)は、最初のメッセージが投稿された後にのみトリガーされます。 - スペースの履歴を変更しても、スペース イベントの更新はトリガーされません(イベントタイプ:
google.workspace.chat.spaces.v1.updated
)。 - メンバーシップ イベントを受信するには、ユーザーがスペースの直接的なメンバーである必要があります。Google グループを介して間接的にスペースに追加、更新、削除された場合、サブスクリプションはこれらのメンバーシップ イベントを受信しません。Google グループのメンバーの仕組みについては、Google グループをスペースに追加するをご覧ください。
関連トピック
- Google Workspace イベントの構造
- OAuth スコープを選択する
- Chat イベントを受信するサブスクリプションを作成する