単純なトリガーと同様に、インストール可能なトリガーを使用すると、ドキュメントを開くなどの特定のイベントが発生したときに Apps Script が自動的に関数を実行できます。ただし、インストール可能なトリガーは、単純なトリガーよりも柔軟性に優れています。認証を必要とするサービスを呼び出したり、時間ドリブン（クロック）トリガーなど、いくつかの追加タイプのイベントを提供したり、プログラムで制御したりできます。シンプルなトリガーとインストール可能なトリガーのどちらの場合も、Apps Script はトリガーされた関数に、イベントが発生したコンテキストに関する情報を含むイベント オブジェクトを渡します。
制限事項
インストール可能なトリガーには単純なトリガーよりも柔軟性がありますが、次のような制限があります。
- ファイルが読み取り専用（表示またはコメント）モードで開かれた場合、実行されません。スタンドアロン スクリプトの場合、トリガーを適切に実行するには、スクリプト ファイルに対する表示以上のアクセス権が必要になります。
スクリプトの実行や API リクエストによってトリガーが実行されることはありません。たとえば、
FormResponse.submit()を呼び出して新しいフォームのレスポンスを送信しても、フォームの送信トリガーは実行されません。インストール可能なトリガーは常に、作成者のアカウントで実行されます。たとえば、インストール可能な Open トリガーを作成すると、同僚がドキュメントを開いたときに（同僚に編集権限がある場合）実行されますが、ユーザー アカウントとして実行されます。つまり、ドキュメントが開かれたときにメールを送信するトリガーを作成すると、メールは常にユーザーのアカウント（ドキュメントを開いたアカウントとは限りません）から送信されます。ただし、アカウントごとにインストール可能なトリガーを作成すると、各アカウントから 1 通のメールが送信されます。
最初のアカウントでは、それらのトリガーを有効にすることはできますが、2 つ目のアカウントからインストールされたトリガーを参照することはできません。
インストール可能なトリガーは、Apps Script トリガーの割り当て上限の対象となります。
時間ドリブンのトリガー
時間ドリブンのトリガー（クロックトリガーとも呼ばれます）は、Unix の cron ジョブに似ています。時間ドリブンのトリガーを使用すると、スクリプトを特定の時刻または定期的な間隔（1 分ごと、月 1 回など）で実行できます。（アドオンでは、時間ドリブンのトリガーを 1 時間に 1 回まで使用できます）。時刻は若干ランダム化されることがあります。たとえば、午前 9 時を繰り返しトリガーする場合、Apps Script は午前 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 スプレッドシートのインストール可能な Open トリガーは、単純な onOpen() トリガーと同様に、編集権限を持つユーザーがスプレッドシートを開くたびに有効になります。ただし、インストール版では、認証を必要とするサービスを呼び出すことができます。インストール可能なバージョンは、トリガーを作成したユーザーの承認で実行されます。これは、編集権限を持つ別のユーザーがスプレッドシートを開いている場合でも同じです。
Google Workspace アプリケーションには、インストール可能なトリガーがいくつかあります。
- インストール可能な open トリガーは、編集権限のあるスプレッドシート、ドキュメント、フォームをユーザーが開いたときに実行されます。
- ユーザーがスプレッドシートの値を変更すると、インストール可能な edit トリガーが実行されます。
- インストール可能な変更トリガーは、ユーザーがスプレッドシート自体の構造を変更（新しいシートの追加や列の削除など）したときに実行されます。
- インストール可能なフォーム送信トリガーは、ユーザーがフォームに回答すると実行されます。form-submit トリガーには、Google フォーム自体とスプレッドシート（フォームがスプレッドシートに送信される場合）の 2 つのバージョンがあります。
- インストール可能なカレンダー イベント トリガーは、ユーザーのカレンダー イベントが更新（作成、編集、削除）されると実行されます。
インストール可能なトリガーは、スタンドアロン スクリプトとバインドされたスクリプトで使用できます。たとえば、スタンドアロン スクリプトでは、TriggerBuilder.forSpreadsheet(key) を呼び出してスプレッドシートの ID を渡すことで、任意の Google スプレッドシート ファイルのインストール可能なトリガーをプログラムで作成できます。
トリガーを手動で管理する
スクリプト エディタでインストール可能なトリガーを手動で作成する手順は次のとおりです。
- Apps Script プロジェクトを開きます。
- 左側の [トリガー] をクリックします。
- 右下の [トリガーを追加] をクリックします。
- 作成するトリガーのタイプを選択して構成します。
- [保存] をクリックします。
トリガーをプログラムで管理する
スクリプト サービスを使用して、プログラムでトリガーを作成および削除することもできます。まず、TriggerBuilder を返す ScriptApp.newTrigger(functionName) を呼び出します。
次の例は、2 つの時間ドリブンのトリガーを作成する方法を示しています。1 つは、6 時間ごとに配信されるトリガーと、もう 1 つは、（スクリプトが設定されているタイムゾーンで）毎週月曜日の午前 9 時に配信されるトリガーです。
次の例は、スプレッドシート用にインストール可能なオープン トリガーを作成する方法を示しています。単純な onOpen() トリガーとは異なり、インストール可能なトリガーのスクリプトをスプレッドシートにバインドする必要はありません。スタンドアロン スクリプトからこのトリガーを作成するには、SpreadsheetApp.getActive() を SpreadsheetApp.openById(id) の呼び出しに置き換えます。
インストール可能な既存のトリガーをプログラムで変更するには、削除して新しいトリガーを作成する必要があります。トリガーの ID を以前に保存している場合は、ID を引数として以下の関数に渡すことで削除できます。
トリガーのエラー
インストール可能なトリガーが起動しても、関数が例外をスローした場合や、正常に実行されなかった場合、画面にエラー メッセージは表示されません。結局、時間ドリブンのトリガーが実行されたり、他のユーザーがフォーム送信トリガーを有効にしたりしても、コンピュータの近くにいないこともあります。
代わりに、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 アカウントに関連付けられているすべてのトリガーを確認して、不要になったトリガーを無効にするには、次の手順を行います。
script.google.comにアクセスします。- 左側の [マイトリガー] をクリックします。
トリガーを削除するには、トリガーの右側にあるその他アイコン > [トリガーを削除] をクリックします。
アドオンのトリガー
アドオンでは、インストール可能なトリガーに加えてマニフェスト トリガーを使用できます。詳細については、Google Workspace アドオンのトリガーをご覧ください。