GAS Properties 儲存腳本資料 (資料庫)

當你需要跨越不同的腳本執行期 (Execution) 儲存資料（例如：API Key、上次處理到的行數、使用者的偏好設定），就必須使用 PropertiesService。這類似於網頁開發中的 localStorage 或應用程式的設定檔。

三種屬性儲存空間

根據資料的使用範圍，GAS 提供了三種等級的儲存空間：

• ScriptProperties：所有使用者共享，且同一個專案的所有執行期皆可讀取。適合存 API Keys。
• UserProperties：僅限「當前使用者」可存取，不同使用者之間資料隔離。適合存個人設定。
• DocumentProperties：屬性綁定在特定的文件 (Sheet/Doc) 上，適合儲存與該檔案相關的狀態。

存取屬性範例

/**
 * 儲存與讀取 API 金鑰
 */
function manageApiKey() {
  const scriptProperties = PropertiesService.getScriptProperties();
  
  // 1. 寫入單一屬性
  scriptProperties.setProperty('API_KEY', 'sk-12345abcde');
  
  // 2. 讀取屬性
  const apiKey = scriptProperties.getProperty('API_KEY');
  console.log(`取得 API Key: ${apiKey}`);
  
  // 3. 移除屬性
  // scriptProperties.deleteProperty('API_KEY');
}

批次寫入與管理

當需要一次儲存多個參數時，批次寫入效能會更好。

function batchSave() {
  const props = PropertiesService.getUserProperties();
  
  // 以物件格式一次設定多個值
  props.setProperties({
    'theme': 'dark',
    'fontSize': '14px',
    'lastLogin': new Date().toString()
  });
  
  // 取得所有屬性
  const allData = props.getProperties();
  console.log(allData['theme']);
}

核心屬性服務函數語法說明

儲存空間取得

• PropertiesService.getScriptProperties()：取得專案級儲存空間。
• PropertiesService.getUserProperties()：取得使用者級儲存空間。

屬性物件方法

• setProperty(key, value)：儲存一個鍵值對 (Key-Value Pair)。注意：value 必須是字串。如果是物件，請先使用 JSON.stringify()。
• getProperty(key)：根據鍵名取得值。
• setProperties(propertiesObject)：批次儲存多個屬性，會覆蓋同名的舊值（除非指定不覆蓋）。
• deleteAllProperties()：清空該儲存空間的所有內容。

儲存空間限制 (Storage Limits)

PropertiesService 雖然好用，但它是為了儲存「小量設定值」而設計的，並不適合當作大型資料庫使用。

實務應用：斷點紀錄 (Checkpoint)

假設你有一個定時器每小時執行一次，負責處理 Gmail 分頁。為了避免重複處理，你可以將「最後處理的 Message ID」存入 UserProperties。下次執行時先讀取該 ID，從該處接續處理，這能有效避免重複發信或處理。