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

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

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

イベント オブジェクトが作成されると、Apps Script はそれをパラメータとして 使用します。トリガー関数はコールバック関数であり、 問題に対処するために適切な行動を起こすよう イベントです。たとえばエディタのアドオンでは を使用して、ドキュメントを開いたときにアドオン メニュー項目を作成します。今回は アドオンのメニュー項目を作成する onOpen(e) トリガー関数に実装します。 必要に応じてイベント オブジェクトのデータを使用します。

このページでは、Google Cloud でトリガーを使用する際の 編集者 できます。

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

Apps Script プロジェクトで使用できるほとんどの汎用トリガータイプを使用できる エディタのアドオン（シンプルなトリガーを含む） およびほとんどのインストール可能なトリガー。「 使用可能なトリガータイプの厳密なセットは、拡張するアプリケーションによって異なります。

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

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

* 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 トリガーは、ユーザーがドキュメントを開いたときに実行されます。 スプレッドシートを開いたときやエディタでフォームを開いたとき（ただし、返信時は対象外） あります）。
• ユーザーがセルの値を変更すると、インストール可能なトリガーを編集して実行 表示されます。このトリガーは、フォーマットなどに応じて配信されません。 セルの値を変わらない変更のみを含めます。
• Change というインストール可能なトリガーは、ユーザーが スプレッドシート（書式設定の編集やスプレッドシートの変更を含む） できます（行の追加など）。

• Google フォームの回答が受信されると、インストール可能な Form-submit トリガーが実行される 送信しました。

• 時間ドリブンのトリガー （クロックトリガーともいいます）特定の時刻に、または一定の時刻に 指定することもできます。

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

通常、開発者がアドオンを更新して、新しいサービスへの 追加の承認が求められると、ユーザーは次のタイミングでアドオンの再承認を求められます。 向上させることができます

ただし、トリガーを使用するアドオンでは特別な承認の課題が発生します。 トリガーを使用してフォームの送信をモニタリングするアドオン、つまりフォームがあるとします。 作成者はアドオンを初めて使用する際に承認し、その後、 フォームを再度開くことなく、数か月から数年間実行し続けることができます。 もし、アドオンのデベロッパーがそのアドオンをアップデートして、 追加の承認が必要な場合、フォーム作成者には ユーザーがフォームを再度開いたことがないため、再承認のダイアログが表示され、 動作しなくなります

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

以下に、トリガー関数で使用する推奨構造の例を示します。 承認の問題を回避できますこのサンプルのトリガー関数は、レスポンス Google スプレッドシートのアドオン内の form-submit イベント。再認証が 必要な場合は、テンプレート化された 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 プロジェクトのインストール可能なトリガーを管理する API です。

これらの制限の他に、インストール可能なコンテナには、 次のような機能が用意されています。

• 各アドオンには、ユーザーごと、ドキュメントごとに、各タイプのトリガーを 1 つだけ設定できます。 たとえば、1 つのスプレッドシートで、1 人のユーザーが編集できるのは 1 回だけです。 ユーザーが、フォーム送信トリガーまたはフォーム送信トリガーを 時間ドリブンのトリガーを使用できます。アクセス権を持つ別のユーザー 独自のトリガーのセットを指定できます。
• アドオンは、アドオンが使用されているファイルに対してのみトリガーを作成できます。 つまり、Google ドキュメント A で使用されているアドオンは、 ドキュメント B を開いたときに監視します。
• 時間ドリブンのトリガーは、1 時間に 1 回を超える頻度で実行できません。
• ユーザーによってコードが実行されても、アドオンはユーザーにメールを自動的に送信しない installable トリガーが例外をスローする。動作の確認は開発者が行います 適切に対処する必要があります。
• 次のいずれかの状況になると、アドオン トリガーの配信が停止します。 <ph type="x-smartling-placeholder">
  </ph>
  • ユーザーがアドオンをアンインストールした場合
  • ドキュメントでアドオンが無効になっている場合（再度有効にすると、トリガー 運用が再開した場合）
  • デベロッパーがアドオンの公開を停止した場合や、破損したバージョンを アドオンストアです
• アドオンのトリガー関数は、使用するコードに到達するまで実行されます 未承認のサービスであると判断した場合は、その時点で停止します。これが当てはまるのは、 アドオンが公開されます。通常の Apps Script プロジェクトでも、 非公開のアドオンが、スクリプトの一部で足りない部分があってもまったく実行されない あります。
• インストール可能なトリガーは Apps Script トリガーの対象になります 割り当て上限が適用されます。