Properties 服务

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

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

货物店对比

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(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. 点击左侧的 Project Settings 图标 。
3. 如需添加第一个属性，请在脚本属性下点击添加脚本属性。
4. 如需添加第二个属性和后续属性，请在脚本属性下点击修改脚本属性 > 添加脚本属性。
5. 对于属性，请输入键名。
6. 对于值，请输入键的值。
7. （可选）要添加更多属性，请点击添加脚本属性。
8. 点击保存脚本属性。

修改脚本属性

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

删除脚本属性

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