房源服务

借助属性服务，您可以将简单数据以键值对的形式存储在以下范围内：一个脚本、一个脚本用户或使用插件的一个文档。它通常用于存储开发者配置或用户偏好设置。属性绝不会在脚本之间共享。

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

媒体资源商店的比较

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

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

数据格式

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

保存数据

如需保存单个值，请调用相应存储区的 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(key)：

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(key)：

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

修改脚本属性

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

删除脚本属性

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