シンプルなトリガー

トリガーを使用すると、ドキュメントを開くなどの特定のイベントが発生したときに、Apps Script で自動的に関数を実行できます。シンプル トリガーは、Apps Script に組み込まれている一連の予約済み関数です。たとえば、ユーザーが Google ドキュメント、スプレッドシート、スライド、フォームのファイルを開いたときに実行される関数 onOpen(e) などがあります。インストール可能なトリガーは、単純なトリガーよりも多くの機能を提供しますが、使用前に有効にする必要があります。どちらのタイプのトリガーでも、Apps Script はトリガーされた関数に、イベントが発生したコンテキストに関する情報を含むイベント オブジェクトを渡します。

注: アドオン プロジェクトでトリガーを使用する方法については、アドオン トリガーをご覧ください。

はじめに

シンプルなトリガーを使用するには、予約済みの関数名のいずれかを使用する関数を作成します。

• onOpen(e) は、ユーザーが編集権限を持っているスプレッドシート、ドキュメント、プレゼンテーション、またはフォームを開くと実行されます。
• onInstall(e) は、ユーザーが Google ドキュメント、スプレッドシート、スライド、フォーム内からエディタ アドオンをインストールすると実行されます。
• onEdit(e) は、ユーザーがスプレッドシートの値を変更すると実行されます。
• onSelectionChange(e) は、ユーザーがスプレッドシートで選択内容を変更すると実行されます。
• doGet(e) は、ユーザーがウェブアプリにアクセスしたとき、またはプログラムが HTTP GET リクエストをウェブアプリに送信したときに実行されます。
• doPost(e) は、プログラムがウェブアプリに HTTP POST リクエストを送信すると実行されます。

上記の関数名の e パラメータは、関数に渡されるイベント オブジェクトです。このオブジェクトには、トリガーを起動したコンテキストに関する情報が含まれていますが、使用は任意です。

制限

シンプルなトリガーはユーザーに承認を求めずに自動的に起動するため、いくつかの制限が適用されます。

• スクリプトは、Google スプレッドシート、スライド、ドキュメント、フォームのファイルにバインドするか、いずれかのアプリケーションを拡張するアドオンにする必要があります。
• ファイルが読み取り専用（表示またはコメント）モードで開かれている場合、これらは実行されません。
• スクリプトの実行や API リクエストではトリガーは実行されません。たとえば、Range.setValue() を呼び出してセルを編集しても、スプレッドシートの onEdit トリガーは実行されません。
• 承認を必要とするサービスにはアクセスできません。たとえば、シンプルなトリガーでは Gmail サービスは承認を必要とするためメールを送信できませんが、単純なトリガーでは匿名の言語サービスでフレーズを翻訳できます。
• バインド先のファイルを変更できますが、承認が必要になるため、他のファイルにアクセスすることはできません。
• 複雑なセキュリティ制限によっては、現在のユーザーの ID を特定できない場合もあります。
• 30 秒を超えて実行することはできません。
• 特定の状況において、エディタ アドオンは onOpen(e) と onEdit(e) のシンプルなトリガーを無許可モードで実行します。これにより、動作がさらに複雑になります。詳細については、アドオン承認ライフサイクルのガイドをご覧ください。
• シンプルなトリガーには、Apps Script トリガーの割り当て上限が適用されます。

これらの制限は doGet(e) と doPost(e) には適用されません。

onOpen(e)

onOpen(e) トリガーは、ユーザーが編集権限のあるスプレッドシート、ドキュメント、プレゼンテーション、またはフォームを開くと自動的に実行されます。（トリガーはフォームに応答するときではなく、フォームを開いて編集するときにのみ実行されます）。onOpen(e) は、Google スプレッドシート、スライド、ドキュメント、フォームにカスタム メニュー項目を追加するためによく使用されます。

trigger/triggers.gs

GitHub で表示

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

onInstall(e) トリガーは、ユーザーが Google ドキュメント、スプレッドシート、スライド、フォーム内からエディタ アドオンをインストールすると自動的に実行されます。ユーザーが Google Workspace Marketplace ウェブサイトからアドオンをインストールする場合、トリガーは実行されません。onInstall(e) が実行できる処理には一定の制限があります。詳しくは、承認をご覧ください。onInstall(e) の最も一般的な使用方法は、単に onOpen(e) を呼び出してカスタム メニューを追加することです。アドオンをインストールすると、ファイルはすでに開いているため、ファイルが再度開かれない限り onOpen(e) は自動的には実行されません。

trigger/triggers.gs

GitHub で表示

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

onEdit(e) トリガーは、ユーザーがスプレッドシート内のセルの値を変更すると、自動的に実行されます。ほとんどの onEdit(e) トリガーは、適切に応答するためにイベント オブジェクトの情報を使用します。たとえば、次の onEdit(e) 関数は、前回の編集時刻を記録するコメントをセルに設定します。

trigger/triggers.gs

GitHub で表示

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

注: onEdit() トリガーがキューに入れるトリガー イベントは最大 2 つのみです。

onSelectionChange(e)

onSelectionChange(e) トリガーは、ユーザーがスプレッドシートで選択を変更すると自動的に実行されます。このトリガーを有効にするには、トリガーを追加してからスプレッドシートを開くたびに、スプレッドシートを更新する必要があります。

選択内容が短時間に複数のセル間を移動する場合、レイテンシを短縮するために、一部の選択変更イベントがスキップされることがあります。たとえば、2 秒以内に多数の選択変更が行われた場合、最初と最後の選択変更のみが onSelectionChange(e) トリガーを有効にします。

以下の例では、空のセルが選択されると、onSelectionChange(e) 関数によってセルの背景が赤に設定されます。

trigger/triggers.gs

GitHub で表示

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e)、doPost(e)

doGet(e) トリガーは、ユーザーがウェブアプリにアクセスするか、プログラムがウェブアプリに HTTP GET リクエストを送信すると自動的に実行されます。doPost(e) は、プログラムが HTTP POST リクエストをウェブアプリに送信すると実行されます。これらのトリガーの詳細については、ウェブアプリ、HTML サービス、コンテンツ サービスのガイドをご覧ください。doGet(e) と doPost(e) には上記の制限がありません。

使用可能なトリガーのタイプ

単純なトリガーの制限が原因でニーズを満たせない場合は、代わりにインストール可能なトリガーが機能することがあります。次の表は、各タイプのイベントで使用できるトリガーのタイプをまとめたものです。たとえば、Google スプレッドシート、スライド、フォーム、ドキュメントではシンプルな起動トリガーがサポートされていますが、インストール可能な起動トリガーをサポートしているのはスプレッドシート、ドキュメント、フォームのみです。

イベント	シンプルなトリガー	インストール可能なトリガー
オープン	スプレッドシート スライド フォーム* ドキュメント function onOpen(e)	スプレッドシート フォーム* ドキュメント
編集	スプレッドシート function onEdit(e)	スプレッドシート
選択の変更	スプレッドシート function onSelectionChange(e)
インストール	スプレッドシート スライド フォーム ドキュメント function onInstall(e)
変更		スプレッドシート
フォームの送信		スプレッドシート フォーム
時間ドリブン（時計）		スプレッドシート スライド フォーム ドキュメント スタンドアロン
Get	スタンドアロン function doGet(e)
投稿	スタンドアロン function doPost(e)

* Google フォームのオープンイベントは、ユーザーが回答のためにフォームを開いたときではなく、エディタがフォームを開いて変更したときに発生します。