房源服务

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

如需查看媒体资源服务的每日配额和存储空间限制，请参阅 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. 点击保存脚本属性。