房源服务

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

如需查看媒体资源服务的每日配额和存储空间限制,请参阅 Google 服务的配额

房源比较

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

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

数据格式

属性服务将所有数据以字符串形式存储为键值对。尚未使用字符串的数据类型会自动转换为字符串,包括已保存对象中包含的方法。

正在保存数据

如需保存单个值,请调用相应存储区的 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 个自定义属性(采用键值对中的字符串形式)。如需添加 50 个以上的属性,您需要使用上述保存数据中所述的方法以编程方式添加这些属性。在项目设置页面设置脚本属性时,您无法引用脚本变量。

添加脚本属性

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

修改脚本属性

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

删除脚本属性

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