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

このページでは、Google Chat アプリが Google Workspace Events API を使用して登録できる Google Chat イベントについて説明します。必要なイベントの種類を決定したら、サブスクリプションを作成して Google Chat からイベントの受信を開始します。

イベントへの登録に加えて、Chat API を呼び出してイベントをクエリすることもできます。Chat API を呼び出すと、イベントを定期的に取得したり、サービス停止のためにサブスクリプションで逃したイベントに追いつくことができます。Chat イベントの受信と応答の方法については、Chat ドキュメントの Google Chat からイベントを操作するをご覧ください。

サポートされている Chat ターゲット リソース

Google Workspace Events API は、以下のサブスクリプションをサポートしています。

  • space リソースとして表されるスペース
  • Cloud Identity API の user リソースとして表されるユーザー

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

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）に登録すると、Chat アプリはバッチ リアクション イベント（google.workspace.chat.reaction.v1.batchCreated）を受信するように自動的に構成されます。

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

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

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 グループを追加するをご覧ください。