房源服务

属性服务以键值对的形式存储数据，这些键值对的范围限定为一个脚本、一个脚本用户或使用插件的一个文档。 它通常用于存储开发者配置或用户偏好设置。属性绝不会在脚本之间共享。

如需查看“房源”服务的每日配额和存储空间限制，请参阅 Google 服务的配额。

属性库比较

PropertiesService 全局对象提供三种方法，每种方法都会返回类似的 Properties 对象，但具有不同的访问权限，如下表所示：

脚本属性 用户属性 文档属性
访问方法 getScriptProperties() getUserProperties() getDocumentProperties()
在以下服务之间共享的数据 脚本、插件或 Web 应用的所有用户 脚本、插件或 Web 应用的当前用户 打开的文档中插件的所有用户
通常用于 应用范围的配置数据，例如开发者的外部数据库的用户名和密码 用户专用设置，例如公制或英制单位 特定于文档的数据，例如嵌入式图表的来源网址

数据格式

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：

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：

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 个自定义属性（以键值对形式的字符串表示）。如需添加 50 个以上的属性，请使用保存数据上一部分中所述的方法以编程方式添加。从项目设置页面设置脚本属性时，请勿引用脚本变量。

添加脚本属性

  1. 打开您的 Google Apps 脚本项目。
  2. 点击左侧的项目设置图标 项目设置的图标。
  3. 如需添加第一个属性，请在脚本属性下点击添加脚本属性。
  4. 如需添加第二个及后续属性，请在脚本属性下，依次点击修改脚本属性 > 添加脚本属性。
  5. 对于属性，请输入密钥名称。
  6. 对于值，输入相应键的值。
  7. （可选）如需添加更多属性，请点击添加脚本属性。
  8. 点击保存脚本属性。

修改脚本属性

  1. 打开您的 Apps 脚本项目。
  2. 点击左侧的项目设置图标 项目设置的图标。
  3. 在脚本属性下，点击修改脚本属性。
  4. 针对要更改的每个属性，更改键名称和键值。
  5. 点击保存脚本属性。

删除脚本属性

  1. 打开您的 Apps 脚本项目。
  2. 点击左侧的项目设置图标 项目设置的图标。
  3. 在脚本属性下，点击修改脚本属性。
  4. 在要删除的媒体资源旁边，点击移除图标 。
  5. 点击保存脚本属性。