范围

用户必须向访问用户数据或代表用户执行操作的插件和其他应用提供授权。当用户首次运行插件时，插件界面会显示启动授权流程的授权提示。

在此流程中，系统会通过提示告知用户应用想要执行哪些操作。例如，某个插件可能需要权限来读取用户的电子邮件或在其日历中创建活动。该插件的脚本项目将这些单个权限定义为 OAuth 范围。

您可以使用网址字符串在manifest中声明范围。在授权流程中，Apps Script 会向用户显示该范围的人类可读说明。例如，您的 Google Workspace 插件可能会使用“读取当前消息”范围，该范围在清单中以 https://www.googleapis.com/auth/gmail.addons.current.message.readonly 的形式编写。在授权流程中，具有此范围的插件会要求用户允许该插件执行以下操作：在该插件运行时查看您的电子邮件。

查看镜重

您可以执行以下操作，查看您的脚本项目目前所需的范围：

  1. 打开脚本项目。
  2. 点击左侧的概览 icon。
  3. 查看“项目 OAuth 范围”下的范围。

您还可以在项目清单的 oauthScopes 字段下查看脚本项目的当前作用域，但前提是您已明确设置这些作用域。

设置显式范围

Apps Script 会扫描脚本代码，找出需要相应作用域的函数调用，从而自动确定脚本需要哪些作用域。对于大多数脚本，这已足够，并且可以节省时间，但对于已发布的插件，您应更直接地控制镜重。

例如，默认情况下，Apps 脚本可能会为插件脚本项目提供非常宽松的 https://mail.google.com 范围。当用户授权具有此范围的脚本项目时，该项目将获得对用户 Gmail 账号的完整访问权限。对于已发布的插件，您必须将此范围替换为仅涵盖插件需求的更有限的范围。

您可以通过修改脚本项目的清单文件来明确设置脚本项目使用的范围。清单字段 oauthScopes 是插件使用的所有镜的数组。如需设置项目的范围，请执行以下操作：

  1. 查看您的插件当前使用的范围。确定需要进行哪些更改，例如使用更窄的范围。
  2. 打开您的插件清单文件。
  3. 找到标记为 oauthScopes 的顶级字段。如果不存在，您可以添加它。

  4. oauthScopes 字段指定一个字符串数组。如需设置项目使用的镜重，请将此数组的内容替换为您希望项目使用的镜重。例如，对于扩展 Gmail 的 Google Workspace 插件，您可能有以下配置：

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}

  5. 保存清单文件更改。

OAuth 验证

使用某些敏感的 OAuth 范围可能需要您的插件先通过 OAuth 客户端验证，然后才能发布。如需了解详情，请参阅以下指南：

受限范围

某些范围属于受限范围，需要遵守有助于保护用户数据的额外规则。如果您打算发布使用一个或多个受限范围的 Gmail 或编辑器插件，该插件必须符合所有指定限制才能发布。

在尝试发布之前，请查看受限范围的完整列表。如果您的插件使用其中任何一种 API，则在发布之前，您必须遵循针对特定 API 范围的其他要求。

为 Google Workspace 插件选择镜重

以下部分提供了 Google Workspace 插件常用的镜重。

编辑器镜重

以下是可对文档、表格和幻灯片进行扩展的 Google Workspace 插件的常用范围。

范围
当前 Google 文档文件访问权限 https://www.googleapis.com/auth/documents.currentonly

如果该插件会访问 Apps Script Docs API，则必须提供此权限。 授予对打开的文档内容的临时访问权限。

当前 Google 表格文件访问权限 https://www.googleapis.com/auth/spreadsheets.currentonly

如果该插件要访问 Apps Script Sheets API，则为必需项。 授予对所打开电子表格内容的临时访问权限。

当前幻灯片文件访问权限 https://www.googleapis.com/auth/presentations.currentonly

如果该插件会访问 Apps Script Slides API，则必须提供此权限。 授予对打开的演示文稿内容的临时访问权限。

按文件访问 https://www.googleapis.com/auth/drive.file

如果插件要使用 onFileScopeGrantedTrigger，并且要访问文档、表格、幻灯片或云端硬盘 API，则必须提供此权限。 使用 Apps 脚本高级云端硬盘服务，按文件授予对应用创建或打开的文件的访问权限。但是，不允许通过基本云端硬盘服务执行类似操作。文件授权是按文件授予的，当用户取消对应用的授权时，授权即会撤消。

Gmail

我们专门为 Google Workspace 插件创建了一些作用域，以帮助保护用户的 Gmail 数据。您必须将这些镜重范围以及您的插件代码所需的任何其他镜重范围明确添加到您的插件清单中。

以下是扩展 Gmail 的 Google Workspace 加购项的常用镜重范围；如果您的加购项扩展了 Gmail，则必须将标记为必需的镜重范围添加到您的 Google Workspace 加购项清单中。

此外，请务必将插件中非常宽泛的 https://mail.google.com 范围替换为一组较小的范围，以允许插件进行所需的交互，而无需执行其他操作。

范围
创建新草稿 https://www.googleapis.com/auth/gmail.addons.current.action.compose

如果该插件使用 撰写操作触发器，则为必需。 允许该插件暂时创建新的草稿邮件和回复。如需了解详情，请参阅撰写草稿消息；此作用域也经常与撰写操作搭配使用。 需要访问令牌。

读取打开的消息元数据 https://www.googleapis.com/auth/gmail.addons.current.message.metadata

授予对打开的邮件的元数据（例如主题或收件人）的临时访问权限。不允许读取消息内容，并且需要访问令牌。

如果插件在 Compose 操作触发器中使用元数据，则必须提供此属性。 对于 Compose 操作，如果 Compose 触发器需要访问元数据，则必须具有此范围。在实践中，此作用域可让“撰写”触发器访问回复电子邮件草稿的收件人名单（“收件人：”“抄送：”和“密送：”）。

阅读打开的消息内容 https://www.googleapis.com/auth/gmail.addons.current.message.action

在用户互动（例如选择插件菜单项）时授予对打开的邮件内容的访问权限。需要访问令牌。
阅读打开的会话内容 https://www.googleapis.com/auth/gmail.addons.current.message.readonly

授予对打开的邮件的元数据和内容的临时访问权限。 此外，还会授予对打开会话中其他消息内容的访问权限。需要访问令牌。

读取任何消息内容和元数据 https://www.googleapis.com/auth/gmail.readonly

读取任何电子邮件元数据和内容，包括已打开的邮件。 如果您需要读取其他邮件的信息（例如执行搜索查询或读取整个邮件会话时），则必须提供此权限。

Google 日历镜重

以下是用于扩展 Google 日历的 Google Workspace 插件常用的镜重。

范围
访问事件元数据 https://www.googleapis.com/auth/calendar.addons.execute

如果插件要访问日历活动元数据，则必须提供此权限。允许该插件访问事件元数据。

读取用户生成的事件数据 https://www.googleapis.com/auth/calendar.addons.current.event.read

如果插件需要读取用户生成的事件数据，则必须提供此权限。 允许该插件访问用户生成的事件数据。只有在 addOns.calendar.eventAccess 清单字段设置为 READ 或 READ_WRITE 时，此类数据才可用。

写入用户生成的事件数据 https://www.googleapis.com/auth/calendar.addons.current.event.write

如果插件需要写入用户生成的事件数据，则必须提供此属性。 允许该插件修改由用户生成的事件数据。只有在 addOns.calendar.eventAccess 清单字段设置为 WRITE 或 READ_WRITE 时，此类数据才可用。

Google 云端硬盘范围

以下是扩展 Google 云端硬盘的 Google Workspace 插件常用的镜重范围。

范围
读取所选内容的元数据 https://www.googleapis.com/auth/drive.addons.metadata.readonly

如果该插件实现了在用户选择 Google 云端硬盘中的项时触发的上下文界面，则必须提供此方法。 允许该插件读取有关用户在 Google 云端硬盘中选择的内容的有限元数据。元数据仅限于内容的 ID、标题、MIME 类型、图标网址，以及该插件是否有权访问相应内容。

按文件访问 https://www.googleapis.com/auth/drive.file

如果插件需要访问个别云端硬盘文件，建议使用此权限。 使用 Apps 脚本高级云端硬盘服务，按文件授予对应用创建或打开的文件的访问权限。不过，这不允许使用基本云端硬盘服务执行类似操作。文件授权是按文件授予的，当用户取消对应用的授权时，授权即会撤消。

请参阅 请求访问所选文件的文件示例。

访问令牌

为保护用户数据，Google Workspace 插件中使用的 Gmail 权限范围仅会授予对用户数据的临时访问权限。如需启用临时访问权限，您必须使用访问令牌作为参数调用函数 GmailApp.setCurrentMessageAccessToken(accessToken)。您必须从操作事件对象获取访问令牌。

以下示例展示了如何设置访问令牌以允许访问消息的元数据。此示例仅需要 https://www.googleapis.com/auth/gmail.addons.current.message.metadata 这一作用域。

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

其他 Google Workspace 权限范围

如果您的插件使用其他 Google Workspace 或 Apps Script 服务，则可能需要额外的范围。 在大多数情况下，您可以让 Apps 脚本检测这些范围并自动更新清单。修改清单的范围列表时，请勿移除任何范围，除非您要用更合适的替代方案（例如更小的范围）替换这些范围。

下表列出了 Google Workspace 插件常用的镜重范围：

范围
读取用户的电子邮件地址 https://www.googleapis.com/auth/userinfo.email

允许项目读取当前用户的电子邮件地址。

允许调用外部服务 https://www.googleapis.com/auth/script.external_request

允许项目发出 UrlFetch 请求。如果项目使用 适用于 Apps 脚本的 OAuth2 库，也需要执行此操作。

读取用户的语言区域和时区 https://www.googleapis.com/auth/script.locale

允许项目了解当前用户的语言区域和时区。 如需了解详情，请参阅访问用户语言区域和时区。

创建触发器 https://www.googleapis.com/auth/script.scriptapp

允许项目创建触发器。

预览第三方链接 https://www.googleapis.com/auth/workspace.linkpreview

如果该插件会预览来自第三方服务的链接，则为必填。 允许项目在用户与 Google Workspace 应用互动时查看应用内的链接。 如需了解详情，请参阅包含智能条状标签的预览链接。

创建第三方资源 https://www.googleapis.com/auth/workspace.linkcreate

如果该插件会在第三方服务中创建资源，则此属性为必需属性。 允许项目读取用户提交到资源创建表单中的信息，并在 Google Workspace 应用中插入指向该资源的链接。 如需了解详情，请参阅通过“@”菜单创建第三方资源。