イベント オブジェクト

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

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

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

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

  ホームページ トリガーの起動時に作成されるイベント オブジェクトには、他の 2 つのケースに含まれるすべてのフィールドは含まれません。ウィジェットとコンテキスト情報に関連するフィールドは省略されます。

• コンテキスト トリガー。各ホスト アプリケーションは、ユーザーが特定のコンテキストを入力したときに起動する、異なるコンテキスト トリガーのセットを提供します。次に例を示します。

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

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

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

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

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

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

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

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

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

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

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

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

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

Calendar イベント オブジェクト

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

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

参加者

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

会議データ

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

エントリ ポイント

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

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

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

ドライブのアイテム

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

Gmail のイベント オブジェクト

Gmail イベント オブジェクトは、イベント オブジェクト全体のうち、ユーザーの Gmail メッセージに関する情報を含む部分です。ホストアプリが Gmail の場合にのみ、イベント オブジェクトに含まれます。

ドキュメント イベント オブジェクト

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

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

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

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

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

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

スライド イベント オブジェクトは、イベント オブジェクト全体の中で、ユーザーのドキュメントとそのコンテンツに関する情報を保有する部分です。ホストアプリが Google スライドの場合にのみ、イベント オブジェクト内に存在します。

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