可安裝的觸發條件

簡單觸發條件類似,可安裝的觸發條件可讓 Apps Script 在發生特定事件 (例如開啟文件) 時自動執行函式。不過,可安裝的觸發條件比簡單觸發條件更具彈性:可呼叫需要授權服務、提供多種額外事件類型 (包括時間驅動 (時鐘) 觸發條件),以及透過程式輔助控制。無論是簡單或可安裝的觸發條件,Apps Script 都會將事件物件傳遞至觸發的函式,其中包含事件發生時的環境資訊。

限制

雖然可安裝的觸發條件比簡單觸發條件更具彈性,但仍須遵守下列幾項限制:

  • 如果檔案是以唯讀 (檢視或加註) 模式開啟,巨集就不會執行。如果是獨立指令碼,使用者至少需要指令碼檔案的檢視權限,觸發條件才能正常執行。
  • 指令碼執行作業和 API 要求不會觸發執行觸發條件。舉例來說,呼叫 FormResponse.submit() 提交新的表單回應時,不會觸發表單的提交觸發程序。

  • 可安裝的觸發條件一律會以建立者的帳戶執行。舉例來說,如果您建立可安裝的開啟觸發條件,當同事開啟文件時 (如果同事具有編輯權限),系統就會執行觸發條件,但會以您的帳戶執行。也就是說,如果您建立觸發條件,在文件開啟時傳送電子郵件,系統一律會從您的帳戶傳送電子郵件,不一定是開啟文件的帳戶。不過,您可以為每個帳戶建立可安裝的觸發條件,這樣每個帳戶都會傳送一封電子郵件。

  • 即使第一個帳戶仍可啟用這些觸發條件,特定帳戶也無法查看從第二個帳戶安裝的觸發條件。

  • 可安裝的觸發條件會受到 Apps Script 觸發條件配額限制

時間型觸發條件

時間觸發條件 (也稱為時鐘觸發條件) 類似於 Unix 中的 cron 工作。時間觸發條件可讓指令碼在特定時間或以固定間隔執行,頻率最高可達每分鐘一次,最低則為每月一次。(請注意,外掛程式最多每小時可使用一次時間觸發條件)。時間可能會稍微隨機,舉例來說,如果您建立上午 9 點的週期性觸發條件,Apps Script 會選擇上午 9 點到 10 點之間的時間,然後每天保持一致,確保觸發條件會在 24 小時後再次觸發。

以事件為準的觸發條件

可安裝的事件導向觸發條件在概念上與簡單觸發條件 (例如 onOpen()) 類似,但可回應其他事件,且行為不同。

舉例來說,Google 試算表的「可安裝的開啟觸發條件」會在任何具有編輯權限的使用者開啟試算表時啟動,就像簡單的 onOpen() 觸發條件一樣。不過,可安裝的版本可以呼叫需要授權服務。即使具有編輯權限的其他使用者開啟試算表,可安裝的版本也會以建立觸發條件的使用者授權執行。

Google Workspace 應用程式可安裝的觸發條件如下:

  • 當使用者開啟有權編輯的試算表、文件或表單時,可安裝的開啟觸發條件就會執行。
  • 當使用者修改試算表中的值時,可安裝的「編輯」觸發條件就會執行。
  • 當使用者修改試算表本身的結構時 (例如新增工作表或移除欄),可安裝的變更觸發條件就會執行。
  • 使用者回覆表單時,可安裝的「表單提交」觸發條件就會執行。 表單提交觸發條件有兩個版本,一個適用於 Google 表單本身另一個適用於表單提交至試算表的情況
  • 當使用者日曆活動更新 (建立、編輯或刪除) 時,可安裝的日曆活動觸發條件就會執行。

您可以在獨立和繫結指令碼中使用可安裝的觸發條件。舉例來說,獨立指令碼可以呼叫 TriggerBuilder.forSpreadsheet(key) 並傳遞試算表 ID,以程式輔助方式為任意 Google 試算表檔案建立可安裝的觸發條件。

手動管理觸發條件

如要在指令碼編輯器中手動建立可安裝的觸發條件,請按照下列步驟操作:

  1. 開啟 Apps Script 專案。
  2. 按一下左側的「觸發條件」圖示
  3. 按一下右下方的「新增觸發條件」
  4. 選取並設定要建立的觸發條件類型。
  5. 按一下 [儲存]

以程式輔助方式管理觸發條件

您也可以使用 Script 服務,以程式輔助方式建立及刪除觸發條件。首先,請呼叫 ScriptApp.newTrigger(functionName),這會傳回 TriggerBuilder

以下範例說明如何建立兩個時間觸發條件:一個每 6 小時觸發一次,另一個則在每週一上午 9 點觸發 (以指令碼設定的時區為準)。

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .everyHours(6)
      .create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

下一個範例說明如何為試算表建立可安裝的開啟觸發條件。請注意,與簡單的 onOpen() 觸發程序不同,可安裝的觸發程序指令碼不需要繫結至試算表。如要從獨立指令碼建立這個觸發條件,只要將 SpreadsheetApp.getActive() 替換為對 SpreadsheetApp.openById(id) 的呼叫即可。

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger('myFunction')
      .forSpreadsheet(ss)
      .onOpen()
      .create();
}

如要以程式輔助方式修改現有的可安裝觸發條件,請刪除該條件並建立新的條件。如果您先前已儲存觸發條件的 ID,可以將該 ID 做為引數傳遞至下列函式,藉此刪除觸發條件。

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

建立觸發條件前,建議先確認相關聯的函式是否具備所有必要的 OAuth 權限

觸發條件發生錯誤

如果可安裝的觸發程序觸發,但函式擲回例外狀況或無法順利執行,畫面上不會顯示錯誤訊息。畢竟,當時間觸發條件執行或有其他使用者啟用表單提交觸發條件時,您可能不在電腦前。

應用程式指令碼會改為傳送類似下方的電子郵件:

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 帳戶相關聯的所有觸發條件,並停用不再需要的觸發條件,請按照下列步驟操作:

  1. 前往 script.google.com
  2. 按一下左側的「我的觸發條件」
  3. 如要刪除觸發條件,請依序點選觸發條件右側的「更多」圖示 >「刪除觸發條件」

外掛程式中的觸發條件

除了可安裝的觸發條件,您也可以在外掛程式中使用資訊清單觸發條件。詳情請參閱「Google Workspace 外掛程式的觸發條件」。