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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

制限事項

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

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

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

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

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

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

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

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

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

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

インストール可能なトリガーの承認

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

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

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

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

コード.gs

triggers/form/Code.gs

GitHub で表示

/**
 * 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.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html

GitHub で表示

<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 トリガーの割り当て上限が適用されます。