高级 Google 服务

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

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

高级服务还是 HTTP?

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

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

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

一般来说,最容易使用高级服务,而且只有在高级服务无法提供您需要的功能时才使用 UrlFetch 方法。

要求

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

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

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

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

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

启用高级服务

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

  1. 打开 Apps 脚本项目。
  2. 点击左侧的 Editor 图标
  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 脚本参考部分的每个高级服务指南中都提供了这些支持说明的链接。