高级 Google 服务

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

启用高级服务

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

第 1 步：启用高级服务

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

方法 A：使用编辑器

  1. 打开 Apps 脚本项目。
  2. 点击左侧的编辑器 。
  3. 在左侧，点击服务旁边的添加服务图标 。
  4. 选择一项高级 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，请执行以下操作：

  1. 在 **Google Cloud 控制台**中打开与脚本关联的 Cloud 项目

  2. 在控制台顶部，点击搜索栏，输入 API 名称的一部分（例如“Calendar”），然后在看到该名称后点击它。

  3. 点击启用 API。

  4. 关闭 Google Cloud 控制台，然后返回到脚本编辑器。

方法签名是如何确定的

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

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

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

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

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

不过，也有一些特殊例外情况需要注意：

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

示例：Calendar.Events.insert

假设您要创建日历活动。 Google Calendar API 文档显示了相应的 HTTP 请求结构：

  • HTTP 动词：POST
  • 请求网址： https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

  • 请求正文：活动资源。

  • 查询参数：sendUpdates、supportsAttachments 等。

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

  1. 正文：活动资源（JavaScript 对象）。
  2. 路径：calendarId（字符串）。
  3. 可选参数：查询参数（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);

我们建议您尽可能使用高级服务，只有在高级服务不可用或无法提供所需功能时才使用 UrlFetch 方法。

支持高级服务

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

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