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

このページでは、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 の次のターゲット リソースをサポートしています。

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

//chat.googleapis.com/spaces/SPACE

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

 サブスクリプションを承認する 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）の新しいメンバーに関するイベントは、最初のメッセージが投稿された後にのみトリガーされます。
  • メンバーシップ イベントを受信するには、ユーザーがスペースの直接的なメンバーである必要があります。Google グループを介してスペースにユーザーが間接的に追加、更新、削除された場合、サブスクリプションにはそれらのメンバーシップ イベントは送信されません。Google グループのメンバーシップの仕組みについては、スペースに Google グループを追加するをご覧ください。