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

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

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

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

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

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

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

注: 現在、Google Workspace アドオンは、一般的な Apps Script のシンプルまたはインストール可能なトリガーを使用できません。代わりに、Google Workspace アドオン用に設計されたトリガーを使用します。詳細については、Google Workspace アドオン トリガーをご覧ください。

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

イベント	イベント オブジェクト	シンプルなトリガー	インストール可能なトリガー
開く エディタ ファイルが開いています。	Docs onOpen イベント オブジェクト Forms onOpen イベント オブジェクト Sheets onOpen イベント オブジェクト Slides 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 フォームの回答が送信されると実行されます。

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

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

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

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

ただし、トリガーを使用するアドオンでは、承認に特殊な課題があります。トリガーを使用してフォームの送信を監視するアドオンを想像してみてください。フォームの作成者は、初めて使用する際にアドオンを承認し、フォームを開かなくても数か月間または数年間実行できます。追加の認証が必要な新しいサービスを使用するようにアドオン デベロッパーがアドオンを更新した場合、フォーム作成者はフォームを再度開くことはなく、アドオンの動作が停止するため、再認証ダイアログは表示されません。

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

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

Code.gs

trigger/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

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