シンプルなトリガー

トリガーを使用すると、ドキュメントを開くなどの特定のイベントが発生したときに、Apps Script で自動的に関数を実行できます。シンプル トリガーは、onOpen(e) のような、Apps Script に組み込まれている一連の予約済み関数です。この関数は、ユーザーが Google ドキュメント、スプレッドシート、スライド、フォームのファイルを開いたときに実行されます。インストール可能なトリガーは、単純なトリガーよりも多くの機能を提供しますが、使用する前に有効にする必要があります。どちらのタイプのトリガーでも、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 スプレッドシート、スライド、ドキュメント、フォームにカスタム メニュー項目を追加するために最もよく使用されます。

triggers/triggers.gs
/**
 * 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)

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

triggers/triggers.gs
/**
 * 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) 関数は、最後に編集された時間を記録するセルにコメントを設定します。

triggers/triggers.gs
/**
 * 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());
}

onSelectionChange(e)

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

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

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

triggers/triggers.gs
/**
 * 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 フォームのオープン イベントは、ユーザーがフォームを開いて回答したときに発生するのではなく、編集者がフォームを開いて変更したときに発生します。