イベント オブジェクト

このページでは、Google Workspace アドオンのイベント オブジェクトの構造について概説します。

イベント オブジェクトは JSON 構造で、ユーザーがアドオンを操作すると自動的に作成され、トリガー関数またはコールバック関数にパラメータとして渡されます。イベント オブジェクトは、ホストアプリと現在のコンテキストに関するクライアントサイド情報をアドオンのサーバーサイド コールバック関数に渡します。

Google Workspace アドオンでは、イベント オブジェクトが次の場所で使用されます。

• ホームページ トリガー。ホームページ トリガー関数がトリガーされると、定義したすべての homepageTrigger 関数にイベント オブジェクトが自動的に渡されます。このオブジェクトは、ホームページ トリガー関数で使用して、アクティブなホストアプリ、クライアントのプラットフォーム、ユーザーの言語 / 地域などの情報を特定できます。

  ホームページのトリガーが実行されたときに作成されるイベント オブジェクトには、他の 2 つのケースに含まれるすべてのフィールドが含まれているわけではありません。ウィジェットとコンテキスト情報に関連するフィールドは省略されます。

• コンテキスト トリガー。各ホスト アプリケーションは、ユーザーが特定のコンテキストに入ったときにトリガーされる一連のコンテキスト トリガーを提供します。次に例を示します。

  • Gmail には、ユーザーがメールを開いたときと、ユーザーがメールを作成したときのコンテキスト トリガーがあります。
  • Google カレンダーには、ユーザーが予定を開いたときのコンテキスト トリガーが用意されています。
  • Google ドライブには、ユーザーがドライブ ファイルを選択したときに実行されるコンテキスト トリガーが用意されています。

  コンテキスト トリガーがトリガーされると、ホスト アプリケーションはアドオン マニフェストにリストされている対応する runFunction を呼び出し、イベント オブジェクトをパラメータとして渡します。コンテキスト トリガーがトリガーされたときに作成されるイベント オブジェクトには、ホームページ トリガーのイベント オブジェクトに含まれるすべてのフィールドに加え、コンテキスト情報が含まれるフィールドが含まれています。

• ウィジェットの操作。イベント オブジェクトは、Gmail アドオンで使用されているのと同じアクション モデルを使用して、ウィジェットのインタラクティビティを提供するためにも使用されます。Google Workspace アドオンは、同じウィジェット ハンドラ関数、Action オブジェクト、アクション レスポンスをすべて使用します。ただし、Google Workspace アドオンのアクション イベント オブジェクトには、コールバック関数で処理できるさらに多くの情報が含まれています。

  ウィジェット アクションの結果として作成されるイベント オブジェクトには、コンテキスト トリガー イベント オブジェクトに含まれるすべてのフィールドと、ウィジェット情報を含むフィールドが含まれます。

• プレビュー リンク トリガー。Google ドキュメント、スプレッドシート、スライドでは、特定の URL パターンに基づいてサードパーティ サービスのリンク プレビューを設定できます。ユーザーがパターンに一致するリンクを操作すると、linkPreviewTriggers がトリガーされ、リンクを含むイベント オブジェクトがトリガーのコールバック関数に渡されます。アドオンはこのイベント オブジェクトを使用して、ホスト アプリケーション内のリンクに関する情報を表示するスマートチップとカードを作成できます。ウィジェット アクションを作成して、ユーザーがプレビュー カードとそのコンテンツを操作できるようにすることもできます。

• Google Chat アプリのトリガー（デベロッパー プレビュー）。Google Chat では、アドオンは Chat アプリとしてユーザーに表示されます。ユーザーは、スペースへの追加、メッセージの送信、スラッシュ コマンドの使用など、アドオンを操作できます。インタラクティブな機能を構築するには、さまざまな Chat アプリ トリガーを設定して使用します。各トリガーは、各タイプのインタラクションを処理または応答するために役立つ異なるイベント オブジェクト ペイロードを送信します。

イベント オブジェクトの構造

次の表に、Google Workspace アドオンのイベント オブジェクトの最上位構造を示します。イベント オブジェクトの構造には、ホストに依存しない情報用の commonEventObject 最上位フィールドが含まれています。各イベント オブジェクトには、アクティブなホストアプリによって決まる、ホスト固有のトップレベル フィールド（gmailEventObject、calendarEventObject、driveEventObject）を 1 つ含めることもできます。

下位互換性を確保するため、Google Workspace アドオンのイベント オブジェクトには、Gmail アドオンのアクション イベント オブジェクトで使用されていた元のフィールドもすべて含まれています。これらのフィールドは、以下の表の「元の Gmail アドオン フィールド」に記載されています。これらのフィールドの情報は、新しいオブジェクト構造で再現されます。

一般的なイベント オブジェクト

共通イベント オブジェクトは、全体のイベント オブジェクトの一部であり、ユーザーのクライアントからアドオンにホストに依存しない一般的な情報を伝達します。この情報には、ユーザーの言語 / 地域、ホストアプリ、プラットフォームなどの詳細が含まれます。

アドオンは、ユーザーがウィジェットを操作したときに、ホームページ トリガーとコンテキスト トリガーに加えて、イベント オブジェクトを作成してアクション コールバック関数に渡します。アドオンのコールバック関数は、共通イベント オブジェクトをクエリして、ユーザーのクライアントで開いているウィジェットのコンテンツを判断できます。たとえば、ユーザーが TextInput ウィジェットに入力したテキストを、eventObject.commentEventObject.formInputs オブジェクトで見つけることができます。

日時選択ツールのフォーム入力

アクション コールバック関数は、commonEventObject.formInputs フィールドで現在のウィジェット値を受信できます。これには、日付選択ツールや時刻選択ツールでユーザーが選択した日付や時刻の値が含まれます。ただし、情報の構造は、ウィジェットが日時選択ツール、日付のみ選択ツール、時刻のみ選択ツールとして構成されているかどうかによって異なります。構造的な違いを次の表に示します。

カレンダーの予定オブジェクト

カレンダー イベント オブジェクトは、ユーザーのカレンダーとカレンダー イベントに関する情報を保持する、イベント オブジェクト全体の一部です。ホスト アプリケーションが Google カレンダーの場合にのみ、イベント オブジェクトに存在します。

次の表に、イベント オブジェクトの calendarEventObject フィールドに存在するフィールドを示します。[ユーザー作成データ] とマークされたフィールドがイベント オブジェクトに存在するのは、データがカレンダー イベントに存在し、アドオンが addOns.calendar.currentEventAccess manifest フィールドを READ または READ_WRITE に設定している場合のみです。

参加者

参加者オブジェクトには、Google カレンダーの予定の個々の参加者に関する情報が格納されます。この情報は、データがカレンダー イベントに存在し、アドオンがその addOns.calendar.currentEventAccess manifest フィールドを READ または READ_WRITE に設定している場合にのみ、イベント オブジェクトに存在します。

会議データ

会議データ オブジェクトには、Google カレンダーの予定に関連付けられている会議に関する情報が格納されます。これらは、Google の会議ソリューション（Google Meet など）またはサードパーティの会議にすることができます。この情報は、データがカレンダーの予定に存在し、アドオンが addOns.calendar.currentEventAccess manifest フィールドを READ または READ_WRITE に設定している場合にのみ、イベント オブジェクトに存在します。

エントリ ポイント

エントリ ポイント オブジェクトには、特定の会議へのアクセス方法（電話やビデオなど）に関する情報が格納されます。この情報は、データがカレンダー イベントに存在し、アドオンが addOns.calendar.currentEventAccess manifest フィールドを READ または READ_WRITE に設定している場合にのみ、イベント オブジェクトに存在します。

ドライブ イベント オブジェクト

Drive イベント オブジェクトは、ユーザーの Google ドライブとそのコンテンツに関する情報を伝達する、イベント オブジェクト全体の一部です。ホスト アプリケーションが Google ドライブの場合にのみ、イベント オブジェクトに存在します。

ドライブのアイテム

ドライブ アイテム オブジェクトには、ファイルやフォルダなど、特定のドライブ アイテムに関する情報が格納されます。

Gmail イベント オブジェクト

Gmail イベント オブジェクトは、ユーザーの Gmail メールに関する情報を伝達するイベント オブジェクト全体の一部です。ホスト アプリケーションが Gmail の場合にのみ、イベント オブジェクトに存在します。

Docs イベント オブジェクト

Docs イベント オブジェクトは、ユーザーのドキュメントとその内容に関する情報を伝達する、イベント オブジェクト全体の一部です。ホスト アプリケーションが Google ドキュメントの場合にのみ、イベント オブジェクトに存在します。

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

スプレッドシートのイベント オブジェクト

Sheets イベント オブジェクトは、ユーザーのドキュメントとその内容に関する情報を伝達する、イベント オブジェクト全体の一部です。ホスト アプリケーションが Google スプレッドシートの場合にのみ、イベント オブジェクトに存在します。

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

スライドのイベント オブジェクト

スライド イベント オブジェクトは、ユーザーのドキュメントとその内容に関する情報を伝達する、イベント オブジェクト全体の一部です。ホスト アプリケーションが Google スライドの場合にのみ、イベント オブジェクトに存在します。

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}