エディタのアドオンに関するトリガー

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

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

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

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

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

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

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

イベント イベント オブジェクト シンプルなトリガー インストール可能なトリガー
開く
エディタ ファイルが開きます。
Docs onOpen イベント オブジェクト
フォームの onOpen イベント オブジェクト
スプレッドシートの onOpen イベント オブジェクト
スライドの onOpen イベント オブジェクト
ドキュメント
フォーム*
スプレッドシート
スライド

function onOpen(e)

ドキュメント
フォーム
スプレッドシート
インストール
アドオンがインストールされています。
onInstall イベント オブジェクト ドキュメント
フォーム
スプレッドシート
スライド

function onInstall(e)

編集
スプレッドシートのセルの内容が変更されました。
スプレッドシートの onEdit イベント オブジェクト スプレッドシート

function onEdit(e)

スプレッドシート
変更
シートのコンテンツが編集または書式設定されます。
スプレッドシートの onChange イベント オブジェクト スプレッドシート
フォーム送信
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 サービスを使用して、インストール可能なトリガーをプログラムで作成および変更できます。アドオンのインストール可能なトリガーを手動で作成することはできません。シンプルなトリガーとは異なり、インストール可能なトリガーでは、承認が必要なサービスを使用できます。

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

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

  • インストール可能なトリガーは、ユーザーがドキュメントやスプレッドシートを開いたとき、またはエディタでフォームを開いたときに実行されます(フォームへの応答時は実行されません)。
  • ユーザーがスプレッドシートのセル値を変更すると、インストール可能な編集トリガーが実行されます。このトリガーは、セル値を変更しない書式設定やその他の変更では起動しません。
  • インストール可能な変更トリガーは、ユーザーがスプレッドシートになんらかの変更を加えると実行されます。たとえば、書式設定の編集やスプレッドシート自体の変更(行の追加など)を行います。
  • Form-submit インストール可能なトリガーは、Google フォームの回答が送信されると実行されます。

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

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

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

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

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

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

コード.gs

trigger/form/Code.gs
/**
 * 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
<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 つのみです。ただし、同じスプレッドシートに form-submit トリガーまたは時間主導トリガーも設定される場合があります。同じスプレッドシートにアクセスできる別のユーザーが、独自のトリガーのセットを持つことができます。
  • アドオンは、アドオンが使用されているファイルに対してのみトリガーを作成できます。つまり、Google ドキュメント A で使用されているアドオンは、Google ドキュメント B を開いたときにモニタリングするトリガーを作成できません。
  • 時間ドリブン トリガーは、1 時間に 1 回を超えて実行することはできません。
  • インストール可能なトリガーによって実行されるコードが例外をスローした場合、アドオンはユーザーにメールを自動的に送信しません。障害のケースを確認して適切に処理するのは、デベロッパー次第です。
  • 次のいずれかの状況で、アドオン トリガーは配信を停止します。
    • ユーザーがアドオンをアンインストールした場合は、
    • ドキュメントでアドオンが無効になっている場合(再度有効にすると、トリガーが再び動作可能になります)
    • デベロッパーがアドオンの公開を停止した場合、または壊れたバージョンをアドオンストアに送信した場合。
  • アドオン トリガー関数は、未承認のサービスを使用するコードに到達するまで実行され、その時点で停止します。これは、アドオンが公開されている場合にのみ当てはまります。スクリプトのいずれかの部分で承認が必要な場合、通常の Apps Script プロジェクトまたは非公開のアドオンの同じトリガーはまったく実行されません。
  • インストール可能なトリガーには、Apps Script トリガーの割り当て上限が適用されます。