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 つだけです。