Google Workspace アドオンのトリガー

Apps Script のトリガーを使用すると、指定されたイベントが発生するたびに、指定されたスクリプト関数（トリガー関数）が実行されます。トリガーをトリガーできるのは特定のイベントのみです。Google Workspace の各アプリケーションは、異なる一連のイベントをサポートしています。

トリガーがトリガーされると、イベント オブジェクトが作成されます。この JSON 構造には、発生したイベントの詳細が含まれます。イベント オブジェクト構造の情報は、トリガーの種類によって編成が異なります。

イベント オブジェクトが作成されると、Apps Script はそれをパラメータとしてトリガー関数に渡します。トリガー関数は、イベントに応じて適切なアクションを実行するために、自分で実装する必要があるコールバック関数です。たとえば、Gmail を拡張する Google Workspace アドオンでは、ユーザーがメッセージ スレッドを開いたときに新しいカード インターフェースを作成するトリガーを定義できます。この場合、コンテキスト コールバック関数を実装して、イベント オブジェクトで渡されたデータを使用して、新しい UI を構成するカードを作成します。

このページでは、Google Workspace アドオン プロジェクトでトリガーを使用する際のガイドラインについて説明します。

マニフェスト トリガー

Editor アドオンとは異なり、Google Workspace アドオンでは現在、Apps Script のシンプルなトリガーを使用できません。代わりに、Google Workspace アドオン専用に設計されたトリガー（マニフェスト トリガー）を使用します。

マニフェスト トリガーは、Google Workspace アドオンのマニフェストで完全に定義されます。マニフェスト トリガーの例を次に示します。

  • アドオンのホームページをビルドして表示するホームページ トリガー。
  • カレンダーの予定の開くトリガー: カレンダーの予定が開かれたときに新しいカードを表示したり、その他のアクションを実行したりします。
  • カレンダーの eventUpdate トリガー: ユーザーがカレンダーの予定を編集して保存したときに、新しいカードを表示したり、その他のアクションを実行したりします。
  • ユーザーがドライブで 1 つ以上のファイルまたはフォルダを選択したときに、新しいカードを表示したり、その他のアクションを実行したりする ドライブの onItemsSelected トリガー。
  • Gmail 作成トリガー: ユーザーが Gmail 作成ウィンドウでアドオンを開いたときに、アドオンカードを表示します。
  • ユーザーが Gmail メールを開いたときに新しいカードを表示したり、その他のアクションを実行したりする Gmail コンテキスト トリガー。
  • Editor onFileScopeGranted トリガー: ユーザーが現在のエディタ ドキュメントで drive.file OAuth スコープの承認を付与すると、新しいカードが表示されます。

上記のリストでは、ホームページ トリガーのみがコンテキスト外で、残りはコンテキスト トリガーです。マニフェスト トリガーの定義の詳細については、マニフェストをご覧ください。

Google Workspace アドオンでは、マニフェスト トリガーに加えて、Apps Script のインストール可能なトリガーも使用できます。

制限事項

マニフェスト トリガーの使用には、一定の制限があります。

  • これらのトリガーは Google Workspace アドオン プロジェクトでのみ使用され、他のアプリケーションでは使用できません。
  • これらのトリガーはコードではなくアドオン マニフェストで定義されるため、Apps Script の Script サービスを使用してこれらのトリガーを作成または変更することはできません。
  • 現在、Gmail コンテキスト トリガーで指定できる条件は unconditional のみです。つまり、コンテキスト トリガーは、コンテンツに関係なくすべてのメール メッセージに対して発動されます。
  • 各アドオンで設定できるトリガーは、ユーザーとドキュメントごとに 1 種類につき 1 つのみです。