物業服務

Properties 服務可讓您將簡單資料儲存在鍵/值組合中，範圍限定為一個指令碼、一個指令碼的使用者，或使用外掛程式的一個文件。通常用於儲存開發人員設定或使用者偏好設定。屬性一律不會在指令碼間共用。

如要查看 Properties 服務的每日配額和儲存空間限制，請參閱「Google 服務的配額」。

屬性儲存庫比較

PropertiesService 全域物件提供三種方法，每種方法都會傳回類似的 Properties 物件，但具有不同的存取權，如下表所示：

指令碼內容 使用者屬性 文件內容
存取方法 getScriptProperties() getUserProperties() getDocumentProperties()
共用資料 所有指令碼、外掛程式或網頁應用程式的使用者 指令碼、外掛程式或網頁應用程式的目前使用者 開啟文件中所有外掛程式的使用者
常用於 應用程式層級設定資料，例如開發人員外部資料庫的使用者名稱和密碼 使用者專屬設定，例如公制或英制單位 文件專屬資料，例如內嵌圖表的來源網址

資料格式

Properties 服務會將所有資料儲存為鍵/值組合中的字串。系統會自動將非字串的資料類型轉換為字串，包括儲存物件內含的方法。

儲存資料

如要儲存單一值，請呼叫適當儲存庫的 Properties.setProperty(key, value) 方法，如以下範例所示：

service/propertyService.gs
try {
  // Set a property in each of the three property stores.
  const scriptProperties = PropertiesService.getScriptProperties();
  const userProperties = PropertiesService.getUserProperties();
  const documentProperties = PropertiesService.getDocumentProperties();

  scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');
  userProperties.setProperty('DISPLAY_UNITS', 'metric');
  documentProperties.setProperty('SOURCE_DATA_ID',
      '1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

如要大量儲存資料，請將鍵/值組合的對應關係傳遞至 Properties.setProperties(properties)。參數中物件的每個鍵/值組合都會儲存為個別的屬性：

service/propertyService.gs
try {
  // Set multiple script properties in one call.
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperties({
    'cow': 'moo',
    'sheep': 'baa',
    'chicken': 'cluck'
  });
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

讀取資料

如要擷取先前儲存的單一值，請呼叫 Properties.getProperty(key)：

service/propertyService.gs
try {
  // Get the value for the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  const units = userProperties.getProperty('DISPLAY_UNITS');
  console.log('values of units %s', units);
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

如要擷取目前屬性儲存庫中的所有值，請呼叫 Properties.getProperties()：

service/propertyService.gs
try {
  // Get multiple script properties in one call, then log them all.
  const scriptProperties = PropertiesService.getScriptProperties();
  const data = scriptProperties.getProperties();
  for (const key in data) {
    console.log('Key: %s, Value: %s', key, data[key]);
  }
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

修改資料

getProperty() 和 getProperties() 方法會傳回儲存資料的副本，而非即時檢視畫面，因此變更已傳回的物件不會更新屬性儲存庫中的值。如要更新儲存庫中的資料，只要再次儲存即可：

service/propertyService.gs
try {
  // Change the unit type in the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  let units = userProperties.getProperty('DISPLAY_UNITS');
  units = 'imperial'; // Only changes local value, not stored value.
  userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

刪除資料

如要刪除單一值，請呼叫 Properties.deleteProperty(key)：

service/propertyService.gs
try {
  // Delete the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('DISPLAY_UNITS');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

如要刪除目前商店中的所有資源，請呼叫 Properties.deleteAllProperties()：

service/propertyService.gs
try {
  // Get user properties in the current script.
  const userProperties = PropertiesService.getUserProperties();
  // Delete all user properties in the current script.
  userProperties.deleteAllProperties();
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

手動管理指令碼屬性

您可以透過專案設定頁面，手動新增最多五十個自訂屬性，以鍵/值組合形式呈現的字串。如要新增超過 50 個屬性，您必須使用程式輔助方式新增屬性，方法請參閱上述「儲存資料」一節。透過專案設定頁面設定指令碼屬性時，您無法參照指令碼變數。

新增指令碼屬性

  1. 開啟 Apps Script 專案。
  2. 按一下左側的「專案設定」圖示 專案設定圖示。
  3. 如要新增第一個資源，請在「Script Properties」下方，點選「Add script property」。
  4. 如要新增第二個屬性和後續屬性，請在「Script Properties」下方依序點選「Edit script properties」>「Add script property」。
  5. 在「Property」中輸入金鑰名稱。
  6. 在「值」中輸入索引鍵的值。
  7. (選用) 如要新增更多資源，請按一下「新增指令碼資源」。
  8. 按一下「儲存指令碼屬性」。

編輯指令碼屬性

  1. 開啟 Apps Script 專案。
  2. 按一下左側的「專案設定」圖示 專案設定圖示。
  3. 在「指令碼屬性」下方，按一下「編輯指令碼屬性」。
  4. 針對要變更的每個屬性，修改鍵名和鍵值。
  5. 按一下「儲存指令碼屬性」。

刪除指令碼屬性

  1. 開啟 Apps Script 專案。
  2. 按一下左側的「專案設定」圖示 專案設定圖示。
  3. 在「指令碼屬性」下方，按一下「編輯指令碼屬性」。
  4. 找出要刪除的資源，然後按一下旁邊的「移除」圖示 。
  5. 按一下「儲存指令碼屬性」。