インストール可能なトリガー

シンプルなトリガーと同様に、インストール可能なトリガーを使用すると、 ドキュメントを開くなどの特定のイベントが発生したときに Google Apps Script が関数を自動的に実行できます。ただし、インストール可能なトリガーは、シンプルなトリガーよりも柔軟性が高く、承認が必要なサービスを呼び出すことができます。また、時間主導型（クロック）トリガーなど、いくつかの追加のイベントタイプが用意されており、プログラムで制御できます。シンプルなトリガーとインストール可能なトリガーの両方で、 Apps Script は、トリガーされた関数に イベント オブジェクトを渡します。これには、イベントが発生したコンテキストに関する情報が含まれています。

アドオンでトリガーを使用する方法について詳しくは、 Google Workspace アドオンのトリガーをご覧ください。

制限事項

インストール可能なトリガーはシンプルなトリガーよりも柔軟性が高いですが、いくつかの制限があります。

  • ファイルが読み取り専用（閲覧またはコメント）モードで開かれている場合、トリガーは実行されません。スタンドアロン スクリプトの場合、トリガーが正しく実行されるには、ユーザーがスクリプト ファイルに対する閲覧権限を持っている必要があります。

  • スクリプトの実行と API リクエストでは、トリガーは実行されません。たとえば、 呼び出し FormResponse.submit() 新しいフォームの回答を送信しても、フォームの送信トリガーは実行されません。

    この制限の例外は Form.submitGrades() です。コードで onFormSubmit トリガーを使用している場合、Form.submitGrades() を呼び出すと onFormSubmit 条件がトリガーされ、無限ループが発生します。無限ループを防ぐには、submitGrades() を呼び出す前に成績がすでに存在するかどうかを確認するコードを追加します。

  • インストール可能なトリガーは、常に作成者のアカウントで実行されます。たとえば、インストール可能なオープン トリガーを作成した場合、同僚がドキュメントを開くと（同僚に編集権限がある場合）、トリガーが実行されますが、あなたのアカウントとして実行されます。つまり、ドキュメントが開かれたときにメールを送信するトリガーを作成した場合、メールは常にあなたのアカウントから送信され、ドキュメントを開いたアカウントから送信されるとは限りません。ただし、アカウントごとにインストール可能なトリガーを作成すると、各アカウントから 1 つのメールが送信されます。

  • あるアカウントが 2 つ目のアカウントからインストールされたトリガーを表示することはできません。ただし、最初のアカウントはそれらのトリガーを有効にできます。

  • インストール可能なトリガーには、Apps Script のトリガーの 割り当て上限が適用されます。

時間主導型トリガー

時間主導型トリガー（クロックトリガーとも呼ばれます）は、Unix の cron ジョブに似ています。時間主導型トリガーを使用すると、スクリプトを特定の時刻に実行したり、1 分ごとや 1 か月ごとなど、定期的に実行したりできます （アドオンでは、時間主導型トリガーを 1 時間に 1 回まで使用できます）。 時間は多少ランダム化されることがあります。たとえば、午前 9 時の定期的なトリガーを作成すると、Apps Script は午前 9 時から午前 10 時までの時間を選択し、そのタイミングを毎日維持して、トリガーが再び起動するまでに 24 時間が経過するようにします。

イベント ドリブン トリガー

インストール可能なイベント ドリブン トリガーは、 シンプルなトリガー（ onOpen()など）と概念的には似ていますが、追加のイベントに応答でき、動作が 異なります。

たとえば、Google スプレッドシートのインストール可能なオープン トリガーは、シンプルな onOpen() トリガーと同様に、編集権限を持つユーザーがスプレッドシートを開くたびに有効になります。ただし、インストール可能なバージョンでは、 承認が必要な サービスを呼び出すことができます。インストール可能なバージョンは、編集権限を持つ別のユーザーがスプレッドシートを開いても、トリガーを作成したユーザーの承認で実行されます。

Google Workspace アプリケーションには、インストール可能なトリガーがいくつかあります。

  • インストール可能なオープン トリガーは、ユーザーが編集権限を持つスプレッドシート、ドキュメント、フォームを開くと実行されます。
  • インストール可能な編集 トリガーは、ユーザーがスプレッドシートの値を変更すると実行されます。
  • インストール可能な変更 トリガーは、ユーザーがスプレッドシート自体の構造を変更すると実行されます（新しいシートを追加したり、列を削除したりするなど）。
  • インストール可能なフォーム送信 トリガーは、ユーザーがフォームに回答すると実行されます。 フォーム送信トリガーには 2 つのバージョンがあります。 1 つは Google フォーム自体用 、もう 1 つはフォームがスプレッドシートに送信される場合のシート用です。
  • インストール可能なカレンダー イベント トリガーは、ユーザーのカレンダー イベントが更新（作成、編集、削除）されると実行されます。

インストール可能なトリガーは、スタンドアロン スクリプトとバインドされたスクリプトで使用できます。たとえば、スタンドアロン スクリプトは、インストール可能なトリガーをプログラムで作成できます。任意の Google スプレッドシート ファイルに対して、TriggerBuilder.forSpreadsheet(key)を呼び出してスプレッドシートの ID を渡すことで作成できます。

トリガーを手動で管理する

スクリプト エディタでインストール可能なトリガーを手動で作成する手順は次のとおりです。

  1. Apps Script プロジェクトを開きます。
  2. 左側の [トリガー] をクリックします。
  3. 右下の [トリガーを追加] をクリックします。
  4. 作成するトリガーのタイプを選択して構成します。
  5. [保存] をクリックします。

トリガーをプログラムで管理する

スクリプト サービスを使用して、トリガーをプログラムで作成および削除します。まず、 ScriptApp.newTrigger(functionName) を呼び出して TriggerBuilder を返します。

次の例は、2 つの時間主導型トリガーを作成する方法を示しています。1 つは 6 時間ごとに起動し、もう 1 つは毎週月曜日の午前 9 時（スクリプトが設定されているタイムゾーン）に起動します。

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger("myFunction")
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.MONDAY)
    .atHour(9)
    .create();
}

次の例は、スプレッドシートのインストール可能なオープン トリガーを作成する方法を示しています。シンプルな onOpen() トリガーとは異なり、インストール可能なトリガーのスクリプトをスプレッドシートにバインドする必要はありません。スタンドアロン スクリプトからこのトリガーを作成するには、SpreadsheetApp.getActive() を SpreadsheetApp.openById(id) の呼び出しに置き換えます。

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();
}

既存のインストール可能なトリガーをプログラムで変更するには、トリガーを削除して新しいトリガーを作成する必要があります。トリガーの ID を以前に保存している場合は、次の関数に ID を引数として渡して削除します。

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

トリガーを作成する前に、関連する関数に必要な OAuth 権限がすべて付与されていることを確認してください。

トリガーのエラー

インストール可能なトリガーが起動しても、関数が例外をスローしたり、正常に実行されなかったりした場合、画面にエラー メッセージは表示されません。時間主導型トリガーが実行されたり、別のユーザーがフォーム送信トリガーを有効にしたりした場合、パソコンの前にいない可能性があります。

代わりに、Apps Script から次のようなメールが送信されます。

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

メールには、トリガーを無効にするか再構成するためのリンクが含まれています。スクリプトが Google スプレッドシート、ドキュメント、フォームの ファイルにバインド されている場合、メールにはそのファイルへのリンクも含まれます。これらのリンクを使用すると、トリガーを無効にしたり、スクリプトを編集してバグを修正したりできます。

スクリプトのエラーをトラブルシューティングするには、通知メールのリンクをクリックしてスクリプト プロジェクトを開きます。プロジェクトが開いたら、左側のナビゲーション パネルで [実行] をクリックして実行ログを表示します。ログには、失敗した実行と、問題の診断と修正に役立つエラー メッセージが表示されます。

アドオンによって作成されたインストール可能なトリガーでは、このようなメール通知はユーザーに送信されません。

Google アカウントに関連付けられているすべてのトリガーを確認し、不要になったトリガーを無効にする手順は次のとおりです。

  1. script.google.com にアクセスします。
  2. 左側の [マイ トリガー] をクリックします。
  3. トリガーを削除するには、トリガーの右側にあるその他アイコン > [**トリガーを削除**] をクリックします。

トリガーが無効になると、対応する失敗通知も無効になります。失敗通知は、有効なトリガーの固有の部分です。 そのため、特定のトリガーのすべての失敗通知の受信を停止するには、トリガー自体を無効にするか削除します。トリガーが有効になっている間は、これらの通知の頻度のみを調整できます。

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

アドオンのトリガー

インストール可能なトリガーに加えて、アドオンでマニフェスト トリガーを使用します。詳しくは、 Google Workspace アドオンのトリガーをご覧ください。