高级 Google 服务

借助 Apps 脚本中的高级服务,经验丰富的开发者 使用某些公共 Google API 所需的设置要比使用其 HTTP 接口少。 高级服务本质上是这些 Google API 的瘦封装容器。他们 与 Apps 脚本的 内置服务,例如它们提供 而 Apps 脚本则会处理 授权流程。 不过,您必须先启用高级服务,然后才能 可以在脚本中使用

要查看哪些 Google API 可用作高级服务,请查找 高级 Google 服务部分(位于 参考文档。如果您想使用 尚未作为高级服务提供,只需像连接其他服务那样 外部 API

高级服务还是 HTTP?

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

如果您使用高级服务方法,Apps 脚本会处理 授权流程和优惠 自动补全支持。但是,您必须 启用高级服务,然后才能使用 。此外,一些高级服务仅提供 功能。

如果您使用 UrlFetch 方法直接访问该 API, 从本质上讲,我们将 Google API 视为 外部 API。通过这种方法, 可以使用该 API 的各个方面。不过,它需要您处理 授权。您还必须构造所需的标头并解析 API 响应。

一般而言,尽可能使用高级服务是最简单的方法, 使用 UrlFetch 方法时,高级服务不提供 所需的全部功能

要求

您必须满足以下条件,才能使用高级服务 要求:

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

    如果您的脚本项目使用默认 GCP 项目 创建日期为 2019 年 4 月 8 日当天或之后创建的 API,则此 API 会自动启用 启用高级服务并保存脚本项目后。如果您 可能还没有进行过相关操作 询问是否同意 Google CloudGoogle API 服务条款。

    如果您的脚本项目使用 标准 GCP 项目 或较旧的默认 GCP 项目 您必须启用高级服务的相应 API 创建项目您必须拥有 GCP 项目的修改权限 进行更改。

请参阅 Cloud Platform 项目

启用高级服务

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

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

启用高级服务后,即可在自动补全功能中找到该服务。

如何确定方法签名

高级服务通常使用相同的对象、方法名称和参数 与相应的公共 API 相同,但方法签名也被转换为 。脚本编辑器的 自动补全功能 通常都能提供充足的信息,方便您轻松上手,以下规则解释了 Apps 脚本如何从公共 Google API 生成方法签名。

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

Google Apps 脚本中对应的方法签名包含以下内容: 参数:

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

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

以下是一些需要注意的特殊例外情况:

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

高级服务支持

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

如果您在使用高级服务时遇到问题, 使用底层 API 的支持说明报告的问题。指向这些内容的链接 帮助中心的各篇高级服务指南中提供了相应的支持说明, Apps 脚本参考部分。