イベント オブジェクト

このページでは、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 フィールドで現在のウィジェット値を受け取ることができます。これには、日付または時刻選択ツール ウィジェットでユーザーが選択した日付または時刻の値が含まれます。ただし、情報の構造は、ウィジェットが日時選択ツール、日付のみ選択ツール、時刻のみ選択ツールのどれに構成されているかによって異なります。次の表に構造上の違いを示します。

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

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

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

参加者

参加者オブジェクトは、個々の参加者に関する情報を 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 の場合にのみ、イベント オブジェクト内に存在します。

Docs イベント オブジェクト

Docs イベント オブジェクトは、イベント オブジェクト全体の中で、ユーザーのドキュメントとそのコンテンツに関する情報を保持する要素です。ホスト アプリケーションが 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"
  }
}