シンプルなトリガー

トリガーを使用すると、ドキュメントを開くなどの特定のイベントが発生したときに、Apps Script によって自動的に関数が実行されます。シンプル トリガーは、Apps Script に組み込まれている予約済み関数のセットです。関数 onOpen(e) は、ユーザーが 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/trigger.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/trigger.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/trigger.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/trigger.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)

スプレッドシート
フォーム*
ドキュメント
Edit
スプレッドシート

function onEdit(e)

スプレッドシート
選択の変更
スプレッドシート

function onSelectionChange(e)

インストール
スプレッドシート
スライド
フォーム
ドキュメント

function onInstall(e)

変更
スプレッドシート
フォーム送信
スプレッドシート
フォーム
時間駆動型(時計)
スプレッドシート
スライド
フォーム
ドキュメント
サイト
スタンドアロン
Get
サイト
スタンドアロン

function doGet(e)

投稿
サイト
スタンドアロン

function doPost(e)

* Google フォームを開くイベントは、ユーザーが回答のためにフォームを開き、編集者がフォームを開いて編集したときには発生しません。