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

シンプル トリガーと同様に、インストール可能なトリガーを使用すると、ドキュメントを開くなどの特定のイベントが発生したときに Apps Script が自動的に関数を実行できます。ただし、インストール可能なトリガーは、単純なトリガーよりも柔軟性が高くなります。つまり、承認が必要なサービスを呼び出すことができます。また、時間駆動(クロック)トリガーなど、複数のタイプのイベントも提供します。また、プログラムで制御することもできます。シンプルなトリガーとインストール可能なトリガーのどちらの場合も、Apps Script は、トリガーされた関数に、イベントが発生したコンテキストに関する情報を含むイベント オブジェクトを渡します。

制限

インストール可能なトリガーは単純なトリガーよりも柔軟性がありますが、いくつかの制限が適用されます。

  • 読み取り専用(表示またはコメント)モードで開いている場合は実行されません。スタンドアロン スクリプトの場合、トリガーを正常に実行するには、少なくともスクリプト ファイルに対する閲覧権限が必要です。
  • スクリプトの実行や API リクエストではトリガーは実行されません。たとえば、FormResponse.submit() を呼び出して新しいフォームの回答を送信しても、フォームの送信トリガーは実行されません。

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

  • 最初のアカウントで 2 番目のアカウントからインストールされたトリガーがあっても、特定のアカウントでそのトリガーを確認することはできません。

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

時間駆動型トリガー

時間駆動トリガー(クロックトリガーとも呼ばれる)は、Unix の cron ジョブに似ています。時間ドリブン トリガーを使用すると、特定の時刻または繰り返しの間隔で、1 分ごとや月 1 回といった頻度でスクリプトを実行できます。(アドオンでは、時間ドリブン トリガーを最大で 1 時間に 1 回まで使用できます)。時刻はわずかにランダム化される場合があります。たとえば、午前 9 時から午前 10 時までの時刻が選択され、そのタイミングが日によって一定に保たれ、トリガーが再び起動されるまで 24 時間経過するなど。

次に示すのは、アプリが存在するすべてのスペースに 1 分ごとにメッセージを投稿する Google Chat アプリの例です。

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

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

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

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

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

  • インストール可能な「開く」トリガーは、ユーザーが編集権限のあるスプレッドシート、ドキュメント、フォームを開くと実行されます。
  • インストール可能な編集トリガーは、ユーザーがスプレッドシートの値を変更すると実行されます。
  • インストール可能な変更トリガーは、ユーザーがスプレッドシート自体の構造を変更したときに実行されます(新しいシートの追加、列の削除など)。
  • インストール可能なフォーム送信トリガーは、ユーザーがフォームに入力すると実行されます。form-submit トリガーには 2 つのバージョンがあります。1 つは Google フォーム自体用で、1 つはスプレッドシート用(フォームがスプレッドシートに送信される場合)です。
  • インストール可能なカレンダーの予定トリガーは、ユーザーのカレンダーの予定が更新(作成、編集、削除)されると実行されます。

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

トリガーを手動で管理

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

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

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

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

次の例は、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;
    }
  }
}

トリガーのエラー

インストール可能なトリガーが配信されても、関数が例外をスローするか、正常に実行に失敗した場合は、画面にエラー メッセージが表示されません。結局のところ、時間ベースのトリガーが実行された場合や、他のユーザーが form-submit トリガーを有効にしたときには、コンピューターにいない状況すらありえます。

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

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Google 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. トリガーを削除するには、トリガーの右側で、その他アイコン > [トリガーを削除] をクリックします。

アドオンでインストール可能なトリガー

アドオンでインストール可能なトリガーを使用する方法については、アドオン トリガーをご覧ください。