エディタ アドオンのトリガー

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

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

イベント オブジェクトが作成されると、Apps Script はそれをパラメータとしてトリガー関数に渡します。トリガー関数は、イベントに応答するために適切なアクションを実行するコールバック関数であり、ユーザーが自分で実装する必要があります。たとえば、エディタ アドオンでは、ドキュメントが開かれたときにアドオン メニュー項目を作成するためにトリガーが使用されます。この場合、onOpen(e) トリガー関数を実装して、アドオンに必要なメニュー項目を作成します。イベント オブジェクトのデータを使用することもできます。

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

エディタ アドオンのトリガータイプ

エディタ用アドオンでは、シンプルなトリガーやほとんどのインストール可能なトリガーなど、Google Apps Script プロジェクトで使用できる汎用トリガー タイプのほとんどを使用できます。使用可能なトリガータイプの正確なセットは、拡張されるアプリケーションによって異なります。

Editor アドオンとは異なり、Google Workspace アドオンでは汎用の Apps Script のシンプルなトリガーやインストール可能なトリガーを使用できません。代わりに、Google Workspace アドオン専用に設計されたトリガーを使用します。詳しくは、Google Workspace アドオンのトリガーをご覧ください。

次の表に、エディタ用アドオンで使用できるシンプルなトリガーとインストール可能なトリガーの種類を示し、対応するイベント オブジェクトへのリンクを示します。

イベント	イベント オブジェクト	シンプルなトリガー	インストール可能なトリガー
開く エディタ ファイルが開きます。	ドキュメントの onOpen イベント オブジェクト フォームの onOpen イベント オブジェクト スプレッドシートの onOpen イベント オブジェクト スライドの onOpen イベント オブジェクト	ドキュメント フォーム* スプレッドシート スライド function onOpen(e)	ドキュメント フォーム スプレッドシート
インストール アドオンがインストールされます。	onInstall イベント オブジェクト	ドキュメント フォーム スプレッドシート スライド function onInstall(e)
編集 スプレッドシートのセルの内容が変更されます。	Sheets の onEdit イベント オブジェクト	スプレッドシート function onEdit(e)	スプレッドシート
変更 スプレッドシートのコンテンツが編集または書式設定された。	スプレッドシートの onChange イベント オブジェクト		スプレッドシート
Form-submit Google フォームが送信されます。	フォームの form-submit イベント オブジェクト スプレッドシートの form-submit イベント オブジェクト		フォーム スプレッドシート
時間駆動型（クロック） 指定された時間または間隔でトリガーが起動します。	時間ドリブン イベント オブジェクト	ドキュメント フォーム スプレッドシート スライド

* Google フォームのオープン イベントは、ユーザーが回答するためにフォームを開いたときではなく、編集者がフォームを修正するために開いたときに発生します。

アドオンのシンプルなトリガー

シンプルなトリガーは、予約済みの関数名を使用し、認可を必要とするサービスを使用できません。また、自動的に有効になり、使用できるようになります。単純なトリガー イベントは、インストール可能なトリガーで処理できる場合があります。

次の予約名のいずれかを使用して関数を実装することで、アドオンにシンプルなトリガーを追加できます。

• onOpen は、ユーザーがドキュメント、スプレッドシート、プレゼンテーションを開いたときに実行されます。onOpen は、フォームがエディタで開かれたときにも実行できます（フォームに回答するときは実行できません）。これは、ユーザーが問題のファイルを編集する権限を持っている場合にのみ実行され、メニュー項目の作成によく使用されます。
• onInstall は、ユーザーがアドオンをインストールしたときに実行されます。通常、onInstall は onOpen を呼び出すためにのみ使用されます。これにより、ユーザーがページを更新しなくても、インストール直後にアドオン メニューが表示されます。
• onEdit は、ユーザーがスプレッドシートのセル値を変更したときに実行されます。このトリガーは、セルの移動、書式設定、セルの値を変更しないその他の変更には反応しません。

制限事項

アドオンのシンプルなトリガーには、他の種類の Apps Script プロジェクトのシンプルなトリガーを管理する制限事項が適用されます。アドオンを設計する際は、特に次の制限事項に注意してください。

• ファイルが読み取り専用（閲覧またはコメント）モードで開かれている場合、単純なトリガーは実行されません。この動作により、アドオン メニューが入力されなくなります。
• 状況によっては、エディタ アドオンは onOpen と onEdit のシンプルなトリガーを承認なしモードで実行します。このモードでは、アドオンの認可モデルで説明されているように、ウォッチフェイスの追加機能が表示されます。
• アドオンの認証モデルで説明されている場合を除き、シンプルなトリガーはサービスを使用したり、認証を必要とするその他のアクションを実行したりすることはできません。
• シンプルなトリガーは 30 秒を超えて実行できません。単純なトリガー関数で実行される処理量を最小限に抑えます。
• 単純なトリガーには、Apps Script トリガーの割り当て上限が適用されます。

アドオンのインストール可能なトリガー

アドオンは、Apps Script の Script サービスを使用して、インストール可能なトリガーをプログラムで作成および変更できます。アドオンのインストール可能なトリガーは手動で作成できません。シンプルなトリガーとは異なり、インストール可能なトリガーは認証を必要とするサービスを使用できます。

アドオンのインストール可能なトリガーは、エラーが発生してもユーザーにエラーメールを送信しません。ほとんどの場合、ユーザーが問題を解決できないためです。そのため、可能な限り、ユーザーに代わってエラーを適切に処理するようにアドオンを設計する必要があります。

アドオンでは、次のインストール可能なトリガーを使用できます。

• Open インストール可能なトリガーは、ユーザーがドキュメントやスプレッドシートを開いたとき、またはフォームがエディタで開かれたときに実行されます（フォームへの回答時を除く）。
• 編集可能なインストール可能トリガーは、ユーザーがスプレッドシートのセル値を変更したときに実行されます。このトリガーは、セルの値を変更しない書式設定などの変更には反応しません。
• 変更可能なトリガーは、ユーザーがスプレッドシートに何らかの変更（書式の編集やスプレッドシート自体の変更（行の追加など））を加えたときに実行されます。

• フォーム送信のインストール可能なトリガーは、Google フォームの回答が送信されたときに実行されます。

  フォーム送信トリガーには 2 つのバージョンがあります。1 つはスプレッドシート用（フォームの回答が収集される場所）、もう 1 つは Google フォーム用です。スプレッドシートのフォーム送信トリガー関数に渡されるイベント オブジェクトはよりシンプルで、レスポンス値を単純な配列で返します。フォーム送信トリガー関数に渡されるイベント オブジェクトには、FormResponse オブジェクトに含まれる詳細情報が提供されます。

• 時間駆動型トリガー（クロック トリガーとも呼ばれます）は、特定の時間に起動するか、一定の間隔で繰り返し起動します。

インストール可能なトリガーを承認する

通常、デベロッパーがアドオンを更新して追加の承認が必要な新しいサービスを使用する場合、ユーザーが次回アドオンを使用する際に、アドオンの再承認を求めるメッセージが表示されます。

ただし、トリガーを使用するアドオンには、特別な承認に関する課題があります。トリガーを使用してフォームの送信をモニタリングするアドオンを考えてみましょう。フォームの作成者は、アドオンを初めて使用するときにアドオンを承認し、その後、フォームを再度開くことなく、数か月または数年間実行し続ける可能性があります。アドオン デベロッパーが、追加の承認を必要とする新しいサービスを使用するようにアドオンを更新した場合、フォーム作成者はフォームを再度開くことがないため、再承認ダイアログが表示されず、アドオンは動作を停止します。

通常の Apps Script プロジェクトのトリガーとは異なり、アドオンのトリガーは再認証が必要な場合でも引き続き起動します。ただし、スクリプトが、必要な権限がないコード行に到達すると、スクリプトは失敗します。これを回避するには、ScriptApp.getAuthorizationInfo を使用して、アドオンのバージョン間で変更されたコードの部分へのアクセスを制御します。

次の例は、承認の落とし穴を回避するためにトリガー関数で使用する推奨構造を示しています。このトリガー関数の例は、Google スプレッドシート アドオン内のフォーム送信イベントに応答し、再認証が必要な場合は、テンプレート化された HTML を使用してアドオンのユーザーにアラート メールを送信します。

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = "My Add-on Title";
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (
    authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.REQUIRED
  ) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty("lastAuthEmailDate");
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile("AuthorizationEmail");
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(
          Session.getEffectiveUser().getEmail(),
          "Authorization Required",
          message.getContent(),
          {
            name: addonTitle,
            htmlBody: message.getContent(),
          },
        );
      }
      props.setProperty("lastAuthEmailDate", today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

制限事項

アドオンのインストール可能なトリガーには、他の種類の Apps Script プロジェクトのインストール可能なトリガーを管理するのと同じ制限が適用されます。

これらの制限に加えて、アドオンのインストール可能なトリガーには、次の制限が適用されます。

• 各アドオンで設定できるトリガーは、ユーザーごと、ドキュメントごとに、各タイプ 1 つのみです。たとえば、特定のスプレッドシートで特定のユーザーが設定できる編集トリガーは 1 つだけです。ただし、同じスプレッドシートでフォーム送信トリガーや時間主導型トリガーを設定することは可能です。同じスプレッドシートにアクセスできる別のユーザーが、独自のトリガー セットを持っている可能性があります。
• アドオンでトリガーを作成できるのは、そのアドオンが使用されているファイルのみです。つまり、Google ドキュメント A で使用されるアドオンは、Google ドキュメント B が開かれたときにモニタリングするトリガーを作成できません。
• 時間主導型トリガーは、1 時間に 1 回以上の頻度で実行できません。
• インストール可能なトリガーによって実行されたコードが例外をスローしても、アドオンからユーザーに自動的にメールが送信されることはありません。障害ケースをチェックして適切に処理するのはデベロッパーの責任です。
• アドオン トリガーは、次のいずれかの状況で配信を停止します。
  • アドオンがユーザーによってアンインストールされた場合、
  • ドキュメントでアドオンが無効になっている場合（再度有効にすると、トリガーが再び動作するようになります）。
  • デベロッパーがアドオンの公開を停止した場合、または破損したバージョンをアドオン ストアに送信した場合。
• アドオンのトリガー関数は、承認されていないサービスを使用するコードに到達するまで実行され、その時点で停止します。これは、アドオンが公開されている場合にのみ当てはまります。通常の Apps Script プロジェクトまたは未公開のアドオンで同じトリガーを使用した場合、スクリプトの一部で承認が必要になると、トリガーはまったく実行されません。
• インストール可能なトリガーには、Apps Script トリガーの割り当て上限が適用されます。