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

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

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

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

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

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

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

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

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

* 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 サービスを使用して、インストール可能なトリガーをプログラムで作成、変更できます。アドオンのインストール可能なトリガーを手動で作成することはできません。シンプルなトリガーとは異なり、インストール可能なトリガーでは、認可が必要なサービスを使用できます。

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

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

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

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

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

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

通常、デベロッパーが追加の承認を必要とする新しいサービスを使用するようにアドオンを更新すると、ユーザーは次回アドオンを使用するときにアドオンの再承認を求められます。

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

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