高级 Google 服务

通过 Google Apps 脚本中的高级服务，您可以连接到某些公共 Google API，所需设置比使用其 HTTP 接口少。高级服务是这些 Google API 的轻量级封装容器。它们的工作方式与 Apps 脚本的内置服务非常相似，例如，它们提供自动补全功能，并且 Apps 脚本会自动处理授权流程。在脚本中使用高级服务之前，请先启用该服务。

启用高级服务

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

第 1 步：启用高级服务

使用 Apps 脚本编辑器或通过修改清单来启用高级服务。

方法 A：使用编辑器

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

方法 B：使用清单

通过修改清单文件来启用高级服务。例如，如需启用 Google 云端硬盘高级服务，请将 enabledAdvancedServices 字段添加到 dependencies 对象：

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

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

第 2 步：启用 Google Cloud API（仅限标准 Google Cloud 项目）

如果使用的是默认 Google Cloud 项目（由 Apps 脚本自动创建），请跳过此步骤。在第 1 步中添加服务时，系统会自动启用该 API。

如果使用的是标准 Google Cloud 项目，请手动启用与高级服务对应的 API。如需手动启用 API，请执行以下操作：

在 ** Google Cloud 控制台** 中打开与脚本关联的云项目
在控制台顶部，点击搜索栏，然后输入 API 名称的一部分（例如“Calendar”），然后在看到该名称后点击它。
点击启用 API 。
关闭 Google Cloud 控制台，然后返回到脚本编辑器。

方法签名是如何确定的

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

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

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

请求正文（通常是资源），以 JavaScript 对象的形式。
路径或必需的参数，以单独的实参的形式。如果方法需要多个路径参数，这些参数会按照其在 API 端点网址中列出的顺序显示。
媒体上传附件，以 Blob 实参的形式。
可选参数（通常是查询参数），以将参数名称映射到值的 JavaScript 对象的形式。
HTTP 请求标头，以将标头名称映射到标头值的 JavaScript 对象的形式。

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

请注意以下例外情况：

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

示例：Calendar.Events.insert

如需创建日历活动，请执行以下操作：

Google 日历 API 文档显示了相应的 HTTP 请求结构：

HTTP 动词: POST
请求网址： https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
请求正文：Event 资源。
查询参数：sendUpdates、supportsAttachments 等。

在 Apps 脚本中，方法签名是通过重新排序这些输入来确定的：

正文：活动资源（JavaScript 对象）。
路径：calendarId（字符串）。
可选参数：查询参数（JavaScript 对象）。

生成的方法调用如下所示：

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

高级服务还是 HTTP？

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

如果您使用高级服务方法，Apps 脚本会处理授权流程并提供自动补全支持。请先启用高级服务，然后再使用它。

如果您使用 UrlFetch 方法直接访问 API，则实际上是将 Google API 视为外部 API。使用此方法时，您可以使用 API 的所有方面。不过，您必须处理 API 授权。

下表对这两种方法进行了比较：

功能	高级服务	UrlFetch (HTTP)
授权	自动处理	需要手动处理
自动补全	可用	不可用
功能范围	可能是 API 的子集	完全访问所有 API 功能
复杂性	降低难度	更复杂（需要构建标头和解析响应）

代码比较

这些代码示例展示了使用高级服务与使用 UrlFetchApp 创建日历活动时复杂性的差异。

高级服务：

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP)：

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

对于 UrlFetchApp 方法，请在脚本的清单文件中手动指定所需的 OAuth 范围。

请尽可能使用高级服务，只有在高级服务不可用或不提供所需功能时才使用 UrlFetch 方法。

对高级服务的支持

由于高级服务是 Google API 的轻量级封装容器，因此在使用高级服务时遇到的任何问题通常都是底层 API 的问题，而不是 Apps 脚本的问题。

如果您在使用高级服务时遇到问题，请按照底层 API 的支持说明报告问题。

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