房源服务

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

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

属性存储区对比

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

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

数据格式

属性服务以键值对的形式将所有数据存储为字符串。系统会自动将非字符串的数据类型转换为字符串，包括保存的对象中包含的方法。

保存数据

如需保存单个值，请调用相应存储区的 Properties.setProperty(key, value) 方法，如以下示例所示：

service/propertyService.gs

在 GitHub 上查看

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

在 GitHub 上查看

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

在 GitHub 上查看

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

在 GitHub 上查看

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

在 GitHub 上查看

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

在 GitHub 上查看

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

在 GitHub 上查看

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. 点击保存脚本属性 。