このページでは、Google Chat アプリが Google Workspace Events API を使用してサブスクライブできる Google Chat イベントについて説明します。必要なイベントの種類を決定したら、サブスクリプションを作成して Google Chat からイベントの受信を開始します。
イベントをサブスクライブするだけでなく、Chat API を呼び出してイベントをクエリすることもできます。Chat API を呼び出すと、定期的にイベントを取得したり、停止により定期購入で受信できなかったイベントを取得したりできます。Chat イベントを受信して応答する方法については、Chat のドキュメントの Google Chat のイベントを操作するをご覧ください。
サポートされている Chat イベント
Google Workspace サブスクリプションを使用すると、Chat で行われた次の種類の変更に関するイベントを受信できます。
- スペース内のメッセージの追加、更新、削除。
- メッセージに対するリアクションの追加または削除。
- スペース内のメンバーの追加、更新、削除。
- 定期購入しているスペースの変更（スペースの名前や説明の更新など）。
イベントをモニタリングできるリソース
イベントを受信するには、モニタリングする Chat リソースを指定します。これは、サブスクリプションのターゲット リソースと呼ばれます。
Google Workspace Events API は、Chat の次のターゲット リソースをサポートしています。
| ターゲット リソース | 形式 | 制限事項 |
|---|---|---|
| スペース |
ここで、SPACE は Chat API |
サブスクリプションを承認する Chat ユーザーは、Google Workspace アカウントまたは Google アカウントを使用してスペースのメンバーである必要があります。 |
| ユーザーのすべてのスペース |
|
定期購入では、ユーザーが Google Workspace または Google アカウントを通じてメンバーになっているスペースのイベントのみが受信されます。 |
| ユーザー |
ここで、USER は Chat API |
サブスクリプションは、サブスクリプションを承認したユーザーに関するイベントのみを受信します。ユーザーは、他のユーザーに代わってサブスクリプションを承認することはできません。 |
サブスクリプションの作成に使用するイベントタイプ
サブスクリプションを作成するときに、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）を定期購入すると、Chat アプリはバッチ リアクション イベント（google.workspace.chat.reaction.v1.batchCreated）を受信するように自動的に構成されます。
次の表に、サブスクリプションに発生する可能性があるバッチイベントを示します。
| バッチイベントの種類 | 形式 |
|---|---|
| 複数のメッセージが投稿されている。 |
|
| 複数のメッセージが更新されます。 |
|
| 複数のメッセージが削除されます。 |
|
| 複数のリアクションが作成されている。 |
|
| 複数のリアクションが削除される。 |
|
| 複数のメンバーが定期購入したスペースに追加されているか、定期購入したユーザーが複数のスペースに追加されている。 |
|
| 定期購入したスペースまたは定期購入したユーザーで、複数のメンバーシップが更新されます。 |
|
| 複数のメンバーが定期購入したスペースから削除された、または定期購入したユーザーが複数のスペースから削除された。 |
|
| スペースに複数の更新がある。 |
|
イベントデータ
このセクションでは、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 グループを介してスペースにユーザーが間接的に追加、更新、削除された場合、サブスクリプションにはそれらのメンバーシップ イベントは送信されません。Google グループのメンバーシップの仕組みについては、スペースに Google グループを追加するをご覧ください。
関連トピック
- Google Workspace イベントの構造
- OAuth スコープを選択する
- Chat イベントを受信するためのサブスクリプションを作成する