GAS Triggers 觸發器：定時與自動化

觸發器 (Triggers) 是 Google Apps Script 的靈魂。它能讓你的程式碼在「不需要手動點擊」的情況下，根據特定事件（如時間到、表單提交、檔案修改）自動執行。

簡單觸發器 (Simple Triggers)

簡單觸發器是內建的保留函數名稱，只要宣告即可使用，不需額外設定。

• onOpen(e)：當試算表、文件或表單開啟時執行。常見於建立自定義選單。
• onEdit(e)：當試算表儲存格被使用者修改時執行。

/**
 * 當試算表被編輯時，自動紀錄修改時間
 */
function onEdit(e) {
  const range = e.range;
  // 僅針對 A 欄進行動作
  if (range.getColumn() === 1) {
    range.offset(0, 1).setValue(new Date()); // 在右側儲存格填入時間
  }
}

Event (e) 物件說明

觸發器執行時會自動傳入一個事件物件 e。

• e.range：被編輯的範圍。
• e.value：修改後的新值。
• e.oldValue：修改前的舊值。
• e.user：執行者的資訊（簡單觸發器有限制）。

可安裝觸發器 (Installable Triggers)

如果你需要讀取個人隱私（例如寄信）或偵測更複雜的事件（例如「表單提交」），必須使用可安裝觸發器。

手動設定方式

1. 在 GAS 編輯器左側點擊「時鐘圖示 (觸發器)」。
2. 點擊「新增觸發器」。
3. 選擇要執行的函數、事件來源（如：來自試算表、時間驅動）。

程式碼建立方式 (Programmatic)

當你需要為使用者動態建立定時任務時，可以使用 ScriptApp。

/**
 * 以程式碼建立一個每小時執行一次的觸發器
 */
function createHourlyTrigger() {
  ScriptApp.newTrigger('myTaskFunction')
    .timeBased()
    .everyHours(1)
    .create();
  
  console.log('每小時觸發器已建立完成');
}

核心觸發器函數語法說明

簡單觸發器限制

• 無法執行需要授權的服務（如 GmailApp）。
• 執行時間上限較短 (30 秒)。
• 事件物件中的 e.user 在某些權限下會是空值。

ScriptApp 觸發器建構器 (Builder)

• ScriptApp.newTrigger(functionName)：指定觸發時要執行的函數名稱。
• timeBased()：進入時間驅動模式。
• forSpreadsheet(ssOrId)：進入試算表驅動模式。
• onFormSubmit()：監聽表單提交。
• everyMinutes(n) / everyHours(n) / everyDays(n)：設定時間頻率。
• atHour(hour)：指定在每天的幾點執行。
• create()：正式在伺服器端建立此觸發器。

執行環境限制 (Quota)

• 執行時間：每次觸發後的執行時間上限約為 6 分鐘（Workspace 為 30 分鐘）。
• 總量限制：每個帳戶能建立的觸發器數量有限（通常每人每種專案約 20 個）。