Google Workspace アドオンのトリガー

Apps Script トリガーは、指定されたイベントが発生するたびに、指定されたスクリプト関数(トリガー関数)を実行します。トリガーを発動できるのは特定のイベントのみで、Google Workspace アプリケーションによってサポートされるイベントのセットは異なります。

トリガーが起動すると、イベント オブジェクトが作成されます。この JSON 構造には、発生したイベントの詳細が含まれています。イベント オブジェクト構造内の情報は、トリガーのタイプに応じて構成が異なります。

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

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

マニフェスト トリガー

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

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

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

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

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

制限

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

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