Google Chat からの予定を管理する

このページでは、Google Chat アプリが Google Chat でイベントを受信して応答する方法について説明します。

Google Chat イベントは、スペース内の新しいメッセージなど、Chat でのアクティビティや変更を表します。Chat アプリは、イベントを使用して何が起こったかを把握し、ユーザーにとって有意義な方法でアクションや応答を行うことができます。

イベントの使用例をいくつかご紹介します。

  • スペース内の新しいメッセージをモニタリングして応答する（キーワードやキーフレーズのチェックなど）。
  • ユーザーがスペースに参加したときにウェルカム メッセージを送信して、スペースのガイドラインを説明したり、Chat 用アプリを効果的に使用するためのヒントを共有したりします。
  • Chat のアクティビティを追跡、分析する。たとえば、新規メンバーや、最も多くのリアクションや返信があったメッセージに関する月次レポートを送信します。
  • 複数のメッセージ プラットフォームに対応。たとえば、ユーザーは Chat を離れることなく、別のメッセージ プラットフォームのユーザーとメッセージを送受信できます。

イベントの仕組み

Google Chat で何かが発生するたびに、Google Chat API リソースが作成、更新、削除されます。Chat は、発生したアクティビティの種類と影響を受けた Chat API リソースに関する情報を Chat アプリに配信するためにイベントを使用します。

Google Chat スペースに投稿されたメッセージがイベントをトリガーする例。
図 1. ユーザーが Chat スペースにメッセージを投稿すると、Message リソースが作成されます。Chat は、新しいメッセージに関するデータを含むイベントを作成します。

Chat では、イベントがタイプ別に分類されます。イベントタイプを使用すると、必要な種類の情報のみをフィルタして受信し、同様のアクティビティを同じ方法で処理できます。

次の表に、Chat でのアクティビティが関連する Chat API リソースにどのように影響するかと、Chat アプリが受信するイベントの種類を示します。

アクティビティ Chat API リソース イベントの種類
ユーザーが Chat スペースにメッセージを投稿する Message リソースが作成されます。 新着メッセージ
ユーザーがスペースの管理者になった。 Membership リソースが更新された。 メンバーシップを更新しました
ユーザーがメッセージにリアクションする。 Reaction リソースが作成されます。 新しいリアクション
ユーザーがスペースから退出した。 Membership リソースが削除された。 削除されたメンバーシップ

Google Chat からイベントを受信する

イベントを受信するには、Chat 用アプリで次のいずれかを行います。

  • Google Workspace Events API を使用してイベントに登録し、イベントが発生したときに受信します。
  • Chat API を呼び出して、最近のイベントをクエリします。

次の表に、イベントのクエリとサブスクライブの違いと理由を示します。

イベントに登録する イベントをクエリする
ユースケース
  • イベントをリアルタイムで処理または対応する。
  • ユーザーのメンバーシップ アクティビティをモニタリングし、モニタリングする新しいスペースを見つけます。
  • イベントを定期的またはトリガーを介して処理または応答する。
  • サブスクリプションから、見逃したイベントを取得します（サービス停止またはサブスクリプションの非アクティブ化が原因）。
API Google Workspace Events API Chat API
イベントのソース スペース、ユーザー、Google Workspace 組織（ デベロッパー プレビュー） スペースのみ
サポートされるイベント
  • メッセージ
  • メンバーシップ
  • リアクション
  • スペース

サポートされているイベントタイプの一覧については、Google Workspace Events API ドキュメントの サブスクリプションを作成するためのイベントタイプをご覧ください。
  • メッセージ
  • メンバーシップ
  • リアクション
  • スペース

サポートされているイベントタイプの一覧については、Chat API リファレンス ドキュメントの spaceEvents リソースをご覧ください。
イベントの形式 CloudEvent 仕様に従ってフォーマットされた Google Cloud Pub/Sub メッセージ。詳しくは、Google Workspace イベントの構造をご覧ください。 Chat API リソース（ spaces.spaceEvent）
イベントデータ リソースデータを含む、または含まない Base64 でエンコードされた文字列。ペイロードの例については、イベントデータをご覧ください。 リソースデータを含む JSON ペイロード。一部のイベントタイプには、特定のリソース フィールドのみが含まれます。ペイロードの例については、 リファレンス ドキュメントをご覧ください。

例: スペースのメンバーシップに関するイベントをクエリまたは登録する

この例では、Chat アプリが Chat スペースのメンバーの変更に関する情報を受信することを想定しています。スペースでは、次のメンバーシップ アクティビティが発生します。

  • ユーザーがスペースに参加すると、Membership リソースが作成され、新規メンバー イベントがトリガーされます。
  • ユーザーがスペースの管理者になると、ユーザーの Membership リソースが更新され、更新されたメンバー イベントがトリガーされます。
  • ユーザーがスペースから退出すると、そのユーザーの Membership リソースが削除され、メンバー削除イベントがトリガーされます。

メンバーシップ イベントに登録する

イベントをリアルタイムで受信するために、Chat 用アプリは Google Workspace Events API の subscriptions.create() メソッドを呼び出して、すべてのタイプのメンバーシップ イベントのスペースに登録します。サブスクリプションを作成すると、Chat 用アプリはメンバーシップ イベントの受信を開始できます。

Google Workspace Events API を使用してイベントに登録する Chat 用アプリ。
図 2. Chat アプリは、Google Workspace Events API を使用してサブスクリプションを通じてメンバーシップ イベントを受信します。

図 2 では、Chat 用アプリにスペースへのアクティブなサブスクリプションがあるため、スペースのメンバーシップが変更されるたびにアプリがイベントを受信します。Chat 用アプリは、スペースに参加したメンバーに非公開のウェルカム メッセージを投稿するなど、アクティビティをリアルタイムで処理したり、アクティビティにリアルタイムで応答したりできます。

Google Workspace Events API を使用してサブスクリプションを作成する方法については、Google Workspace Events API のドキュメントをご覧ください。

最近のメンバーシップ イベントをクエリする

メンバーシップ イベントが発生したときに受信する代わりに、Chat アプリは Chat API を呼び出して、メンバーシップ アクティビティに関連する最近のスペース イベントを一覧表示できます。

Chat API を使用してイベントをクエリする Chat 用アプリ。
図 3. Chat アプリは、Chat API を使用してスペース イベントをクエリすることで、最近のメンバーシップ イベントを受信します。

図 3 では、すべてのメンバーシップ アクティビティが発生した後に、Chat 用アプリが Chat API の spaces.spaceEvents.list() メソッドを呼び出し、新規、更新、削除されたメンバーシップ イベントのクエリをフィルタします。Chat API は、各メンバーシップの変更を表す spaceEvent リソースのリストを返します。Chat 用アプリは、最近のアクティビティに基づいて処理または応答できます。たとえば、過去 7 日間のスペースのメンバー アクティビティの概要を含む週次メッセージを投稿できます。

Chat API を使用してイベントをクエリするには、Google Chat スペースのイベントを一覧表示するをご覧ください。

制限事項と配信動作

一般的な制限事項

  • メンバーシップ イベントを受信するには、ユーザーまたは Chat 用アプリがスペースの直接メンバーである必要があります。Google グループを介してスペースに間接的に追加、更新、削除された場合、サブスクリプションはそれらのメンバーシップ イベントを受信しません。Google グループのメンバーシップの仕組みについては、スペースに Google グループを追加するをご覧ください。

ユーザーの登録

  • ユーザーへのサブスクリプションの場合、ダイレクト メッセージまたは名前のないグループ チャット（google.workspace.chat.membership.v1.created）の新規メンバーに関するイベントは、最初のメッセージが投稿された後にのみトリガーされます。

お客様のサブスクリプション

お客様のサブスクリプションには、次の制限が適用されます。

  • Google Workspace 組織に少なくとも 1 つの Enterprise SKU ライセンスが必要です。
  • Chat 用アプリが特定の Google Workspace 組織に対して作成できるお客様のサブスクリプションは 1 つのみです。Google Workspace 組織は、合計で最大 5 つのお客様サブスクリプション（異なる Chat アプリによって作成されたもの）を持つことができます。

お客様のサブスクリプションの場合、イベント配信は次の一般的なルールに従います。

  • スペース イベント: Google Workspace 組織が管理するスペースでイベントが発生した場合にのみ配信されます。
  • ユーザー イベント: Google Workspace 組織に属するユーザーに対してイベントが発生した場合にのみ配信されます。

これらのルールの唯一の例外は、メンバーシップ イベントです。サブスクリプションは、組織が管理するスペースと外部組織が管理するスペースの両方からメンバーシップ イベントを受信できますが、配信方法はスペースを管理する組織によって異なります。

Google Workspace 組織によって管理されているスペース

Google Workspace 組織が管理するスペースでメンバーシップの変更が発生すると、スペース イベントとして配信されます。

スペース イベントのリソース名は、次の形式を使用します。

spaces/{spaceId}/spaceEvents/{spaceEventId}

外部組織によって管理されているスペース

Google Workspace 組織が管理するユーザーのメンバーシップが、外部組織が管理するスペース（外部の名前付きスペースや外部ユーザーが作成したダイレクト メッセージなど）で変更された場合、サブスクリプションはこのイベントをユーザー イベントとして受信します。

ユーザー イベントのリソース名は、次の形式を使用します。

users/{userId}/userEvents/{userEventId}