シンプルなトリガー

トリガーを使用すると、特定のイベント(ドキュメントを開くなど)が発生したときに 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 スプレッドシート、スライド、ドキュメント、フォームにカスタム メニュー項目を追加するために使用されます。

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)

onInstall(e) トリガーは、ユーザーが Google ドキュメント、スプレッドシート、スライド、フォームからエディタ アドオンをインストールすると自動的に実行されます。ユーザーが 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 フォームのオープン イベントは、ユーザーが回答のためにフォームを開いたときではなく、編集者がフォームを開いて変更したときに発生します。