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

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

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

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

Google Workspace サブスクリプションでは、Chat で行われた次の種類の変更に関するイベントを受信できます。

  • スペース内の新しいメッセージ、更新されたメッセージ、削除されたメッセージ。
  • メッセージに対するリアクションの追加または削除。
  • スペース内のメンバーの追加、更新、削除。
  • 登録しているスペースへの変更（スペースの名前や説明の更新など）。

イベントをモニタリングできるリソース

イベントを受信するには、モニタリングする Chat リソースを指定します。これは、サブスクリプションのターゲット リソースと呼ばれます。

Google Workspace Events API は、Chat の次のターゲット リソースをサポートしています。

ターゲット リソース 形式 制限事項
スペース

//chat.googleapis.com/spaces/SPACE

ここで、SPACE は Chat API の space リソースの リソース名の ID です。ID は、スペースの URL から取得するか、 spaces.list() メソッドを使用して取得できます。

 サブスクリプションを承認する Chat ユーザーまたは Chat 用アプリは、Google Workspace アカウントまたは Google アカウントを通じてスペースのメンバーである必要があります。サポート対象:
ユーザーのすべてのスペース

//chat.googleapis.com/spaces/-

 サブスクリプションは、ユーザーが Google Workspace または Google アカウントを通じてメンバーになっているスペースのイベントのみを受信します。ユーザー認証のみをサポートします。
ユーザー

//cloudidentity.googleapis.com/users/USER

ここで、USER は Chat API の user リソースの リソース名の ID です。詳しくは、Google 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/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

リソースデータを除外します。

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
ユーザーがスペースの管理者になる。

google.workspace.chat.membership.v1.updated

リソースデータが含まれます。

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}

リソースデータを除外します。

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
ユーザーがスペースの説明を「Cymbal Labs の営業チーム」に更新します。 google.workspace.chat.space.v1.updated

リソースデータが含まれます。

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}

リソースデータを除外します。

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
2 人の Chat ユーザーが同時にスペースに追加されました。 google.workspace.chat.membership.v1.batchCreated

リソースデータが含まれます。

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

リソースデータを除外します。

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
ユーザーが 😊 絵文字でメッセージにリアクションしている。 google.workspace.chat.reaction.v1.created

リソースデータが含まれます。

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

リソースデータを除外します。

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
ユーザーが 😊 絵文字と 😸 絵文字でメッセージにリアクションします。 google.workspace.chat.reaction.v1.batchCreated

リソースデータが含まれます。

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

リソースデータを除外します。

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}

制限事項
  • ユーザーのサブスクリプションの場合、ダイレクト メッセージまたは名前のないグループ チャット（google.workspace.chat.membership.v1.created）の新しいメンバーに関するイベントは、最初のメッセージが投稿された後にのみトリガーされます。
  • メンバーシップ イベントを受信するには、ユーザーまたは Chat 用アプリがスペースの直接のメンバーである必要があります。Google グループ経由でスペースに間接的に追加、更新、削除された場合、サブスクリプションはこれらのメンバーシップ イベントを受け取りません。Google グループのメンバーシップの仕組みについては、スペースに Google グループを追加するをご覧ください。