高级 Google 服务

借助 Apps Script 中的高级服务，经验丰富的开发者可以连接到某些公共 Google API，所需设置比使用其 HTTP 接口少。高级服务本质上是这些 Google API 的轻量封装容器。它们的运作方式与 Apps Script 的内置服务非常相似，例如，它们提供自动补全功能，而 Apps Script 会自动处理授权流程。不过，您必须先启用高级服务，然后才能在脚本中使用该服务。

如需查看哪些 Google API 可用作高级服务，请参阅参考文档中的 Advanced Google Services（高级 Google 服务）部分。如果您想使用无法作为高级服务使用的 Google API，只需像连接任何其他外部 API 一样连接到该 API 即可。

高级服务还是 HTTP？

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

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

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

一般来说，尽可能使用高级服务是最简单的方法，只有当高级服务无法提供您所需的功能时，才应使用 UrlFetch 方法。

要求

您必须满足以下要求，才能使用高级服务：

  1. 您必须在脚本项目中启用高级服务。

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

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

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

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

启用高级服务

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

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

启用高级服务后，该服务便会显示在自动补全功能中。

如何确定方法签名

高级服务通常使用与相应公共 API 相同的对象、方法名称和参数，但方法签名会经过转换，以便在 Apps 脚本中使用。脚本编辑器的自动补全功能通常会提供足够的信息来帮助您入门，但以下规则介绍了 Apps Script 如何根据公共 Google API 生成方法签名。

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

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

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

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

请注意以下一些特殊例外情况：

  • 对于接受媒体上传内容的方法，系统会自动设置参数 uploadType。
  • 由于 delete 是 JavaScript 中的保留字，因此 Google API 中名为 delete 的方法在 Apps Script 中名为 remove。
  • 如果高级服务配置为接受 HTTP 请求标头，并且您设置了请求标头 JavaScript 对象，则还必须设置可选参数 JavaScript 对象（如果您不使用可选参数，则将其设置为空对象）。

支持高级服务

高级服务只是薄封装容器，可让您在 Apps 脚本中使用 Google API。因此，在使用这些函数时遇到的任何问题通常是底层 API 的问题，而不是 Google Apps Script 本身的问题。

如果您在使用高级服务时遇到问题，应按照底层 API 的支持说明进行报告。Apps Script 参考文档部分中的每份高级服务指南都提供了指向这些支持说明的链接。