Google Chat のイベントに登録する

このページでは、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 イベントの構造をご覧ください。

次の表に、スペースへの登録とユーザーの登録でサポートされるイベントタイプを示します。イベントをトリガーする例外については、制限事項をご覧ください。

イベントの種類 形式 リソースデータ
スペースへの登録  
メッセージが投稿されます。

google.workspace.chat.message.v1.created

space.message
メッセージが更新される。

google.workspace.chat.message.v1.updated

space.message
メッセージが削除された。

google.workspace.chat.message.v1.deleted

space.message
リアクションが作成されます。

google.workspace.chat.reaction.v1.created

space.message.reaction
リアクションが削除されました。

google.workspace.chat.reaction.v1.deleted

space.message.reaction
メンバーがスペースに追加されます。

google.workspace.chat.membership.v1.created

space.membership
スペース内のメンバーが更新される。

google.workspace.chat.membership.v1.updated

space.membership
メンバーがスペースから削除されます。

google.workspace.chat.membership.v1.deleted

space.membership
スペースが更新されます。

google.workspace.chat.space.v1.updated

space
スペースは削除されます。

google.workspace.chat.space.v1.deleted

space
ユーザーのサブスクリプション  
ユーザーがスペースのメンバーになります。

すべての新しいメンバーがイベントをトリガーするわけではありません。詳細については、制限事項をご覧ください。

google.workspace.chat.membership.v1.created

space.membership
スペースへのユーザーのメンバーシップが更新されます。

google.workspace.chat.membership.v1.updated

space.membership
そのユーザーはスペースの直接のメンバーから削除されます。

google.workspace.chat.membership.v1.deleted

space.membership

バッチ イベントタイプ（出力のみ）

Chat アプリは、サブスクライブしているイベントタイプを受信するだけでなく、バッチイベントも受信する場合があります。バッチイベントは、短期間に発生する同じタイプの多数のイベントを表すイベントです。バッチイベントのペイロードには、変更されたすべてのリソースのリストが含まれます。

たとえば、ユーザーが同時に 20 人のユーザーをスペースに追加すると、Chat アプリはバッチイベント（google.workspace.chat.membership.v1.batchCreated）を受信する可能性があります。イベント ペイロードには、ユーザーがスペースにメンバーを追加したときに作成されたすべての新しい Membership リソースのリストが含まれます。

サブスクライブしているすべてのイベントタイプのバッチイベントを受け取るため、サブスクリプションの作成時にバッチイベントを指定する必要はありません。たとえば、新しいリアクション（google.workspace.chat.reaction.v1.created）に登録すると、バッチ リアクション イベント（google.workspace.chat.reaction.v1.batchCreated）を受信するように Chat アプリが自動的に構成されます。

次の表に、サブスクリプションで発生する可能性のあるバッチ イベントを示します。

バッチイベントタイプ 形式
複数のメッセージが投稿されます。

google.workspace.chat.message.v1.batchCreated
複数のメッセージが更新されました。

google.workspace.chat.message.v1.batchUpdated
複数のメッセージが削除されます。

google.workspace.chat.message.v1.batchDeleted
複数のリアクションが作成されます。

google.workspace.chat.reaction.v1.batchCreated
複数のリアクションが削除されます。

google.workspace.chat.reaction.v1.batchDeleted
登録済みスペースに複数のメンバーが追加されたか、登録済みユーザーが複数のスペースに追加されている。

google.workspace.chat.membership.v1.batchCreated
登録済みスペースまたは登録済みユーザーの複数のメンバーシップが更新されます。

google.workspace.chat.membership.v1.batchUpdated
登録済みスペースから複数のメンバーが削除されたか、登録済みユーザーが複数のスペースから削除されています。

google.workspace.chat.membership.v1.batchDeleted
スペースに複数の更新があります。

google.workspace.chat.space.v1.batchUpdated

イベントデータ

このセクションでは、Chat でのイベントのイベントデータとサンプル ペイロードについて説明します。

Google Workspace サブスクリプションが Chat からイベントを受信すると、data フィールドにそのイベントのペイロードが含まれます。このペイロードには、変更された Google Workspace リソースに関する情報が含まれています。たとえば、スペースのメンバーシップ イベントに登録している場合、これらのイベントのペイロードには、変更された spaces.membership リソースに関する情報が含まれます。

イベント ペイロード内のリソースデータ

サブスクリプションを作成するときに、ペイロードにリソースの詳細を含めるか、リソースの名前のみを含めるかを指定できます。たとえば、Chat スペースのメンバーに関するイベントを受信する場合は、イベント ペイロードで受信するメンバーシップ リソースのフィールドを指定できます。

次の表に、Chat スペース spaces/AAAABBBBBB のサブスクリプションの JSON ペイロードの例を示します。定期購入が受信するイベントごとに、ペイロードがイベントの data フィールドに表示されます。

例 イベントの種類 JSON ペイロード

ユーザーが「Hello World」というメッセージをスペースに投稿します。

google.workspace.chat.message.v1.created

リソースデータが含まれます
{
    "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"
    }
}
ユーザーがスペースの管理者になります。

google.workspace.chat.membership.v1.updated

リソースデータが含まれます
{
    "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 グループをスペースに追加するをご覧ください。