高级 Google 服务

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

借助 Apps 脚本的高级服务,经验丰富的开发者只需完成较少的设置,即可连接到某些公开的 Google API。高级服务实质上是这些 Google API 的瘦封装容器。它们的工作原理与 Apps 脚本的内置服务非常相似。例如,它们提供自动补全功能,而 Apps 脚本会自动处理授权流程。不过,您必须先启用高级服务,然后才能在脚本中使用该服务。

如需了解哪些 Google API 可作为高级服务使用,请查找参考文档中的高级 Google 服务部分。如果您要使用的 Google API 不作为高级服务提供,只需像任何其他外部 API 一样连接到该服务。

高级服务还是 HTTP?

每项高级 Google 服务都与一个公共 Google API 相关联。在 Apps 脚本中,您可以通过高级服务访问这些 API,或直接使用 UrlFetch 发出 API 请求。

如果您使用高级服务方法,则 Apps 脚本会处理授权流程并提供自动补全支持。不过,您必须先启用高级服务,然后才能使用该服务。此外,某些高级服务仅提供 API 中提供的部分功能。

如果您使用 UrlFetch 方法直接访问 API,您实际上是在将 Google API 视为外部 API。通过此方法,可以使用该 API 的所有方面。但是,您需要自行处理 API 授权。您还必须构建任何所需的标头并解析 API 响应。

一般来说,使用高级服务是最简便的,并且仅在高级服务未提供您所需的功能时才使用 UrlFetch 方法。

要求

在使用高级服务之前,您必须满足以下要求:

  1. 您必须在脚本项目中启用高级服务
  2. 请务必在您的脚本使用的 Cloud Platform (GCP) 项目中启用与高级服务对应的 API。

    如果您的脚本项目使用 2019 年 4 月 8 日当天或之后创建的默认 GCP 项目,则在您启用高级服务并保存脚本项目后,系统会自动启用 API。您可能还需要同意 Google Cloud PlatformGoogle API 服务条款(如果您尚未这样做)。

    如果您的脚本项目使用标准 GCP 项目或较旧的默认 GCP 项目,您必须在 GCP 项目中手动启用高级服务的相应 API。您必须拥有 GCP 项目的修改权限才能进行此更改。

如需了解详情,请参阅 Cloud Platform 项目

启用高级服务

要使用 Google 高级服务,请按以下说明操作:

  1. 打开 Apps 脚本项目。
  2. 点击左侧的编辑器图标
  3. 在左侧服务旁边,点击添加服务
  4. 选择一项高级 Google 服务,然后点击添加

启用高级服务后,该服务会在自动补全中显示。

如何确定方法签名

高级服务通常会使用与相应的公共 API 相同的对象、方法名称和参数,不过方法签名已经过转换,可在 Apps 脚本中使用。脚本编辑器的自动补全函数通常会提供足够的入门信息,但以下规则说明了 Apps 脚本如何从公共 Google API 生成方法签名。

向 Google API 发出的请求可接受各种不同类型的数据,包括路径参数、查询参数、请求正文和/或媒体上传附件。某些高级服务还可以接受特定的 HTTP 请求标头(例如日历高级服务)。

Google Apps 脚本中的相应方法签名具有以下参数:

  1. 请求正文(通常是资源),以 JavaScript 对象的形式表示。
  2. 路径或必需参数,作为单独的参数。
  3. 媒体上传附件,作为 Blob 参数。
  4. 可选参数,作为将参数名称映射到值的 JavaScript 对象。
  5. HTTP 请求标头,作为将标头名称映射到标头值的 JavaScript 对象。

如果该方法在给定类别中没有任何项,则省略该部分签名。

有一些特殊例外情况需要注意:

  • 对于接受媒体上传的方法,系统会自动设置参数 uploadType
  • 在 Google API 中,名为 delete 的方法在 Apps 脚本中被命名为 remove,因为 delete 是 JavaScript 中的保留字。
  • 如果高级服务配置为接受 HTTP 请求标头,并且您设置了请求标头 JavaScript 对象,则还必须设置可选参数 JavaScript 对象(如果您没有使用可选参数,请将其设置为空对象)。

支持高级服务

高级服务只是可在 Apps 脚本中使用 Google API 的瘦封装容器。因此,在使用它们时遇到的任何问题通常是底层 API 的问题,而不是 Apps 脚本本身的问题。

如果您在使用高级服务时遇到问题,应根据底层 API 的支持说明报告该问题。Apps 脚本参考部分的每个高级服务指南中都提供了这些支持说明的链接。