范围

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

在此流程中，提示会告知用户应用需要哪些权限。例如，插件可能需要读取用户电子邮件或在日历中创建活动的权限。插件的脚本项目会将这些单独的权限定义为 OAuth 范围 。

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

Apps 脚本用于其各种服务的范围与相关 API 使用的范围重叠。例如，Apps 脚本的 日历服务 使用许多与 Calendar API 相同的范围。您可以在 Apps 脚本参考文档 中查找特定 Apps 脚本服务方法 所需的范围。

查看范围

您可以按照以下步骤查看脚本项目当前需要的范围：

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

您还可以在项目清单的脚本项目的当前范围， 在 oauthScopes 字段下，但前提是您已明确设置了这些范围。

设置明确范围

Apps 脚本会扫描脚本的代码，查找需要范围的函数调用，自动确定脚本需要哪些范围。自动扫描可以满足大多数脚本的需求，并且可以节省时间，但对于已发布的插件，您应直接控制范围。

例如，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 客户端验证 ，然后才能发布。如需了解详情，请参阅以下指南：

• 适用于 Apps 脚本的 OAuth 客户端验证
• 未经验证的应用
• OAuth 验证常见问题解答
• Google API 服务：用户数据政策

受限范围

某些范围是 受限的 ，并且受有助于保护用户数据的其他规则的约束。如果您打算发布使用一个或多个受限范围的 Gmail 或编辑器插件，则该插件必须符合所有指定的限制，然后才能发布。

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

Visual Studio Code 的 Google Workspace 开发者工具扩展程序 会提供所有范围的诊断信息，包括 范围的说明以及范围是否敏感或受限。

为 Google Workspace 插件选择范围

以下部分提供了 Google Workspace 插件常用的范围。

编辑器范围

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

Gmail

系统专门为 Google Workspace 插件创建了一些范围，以帮助保护用户 Gmail 数据。将这些范围以及任何其他必需范围明确添加到插件清单中。

下表列出了扩展 Gmail 的 Google Workspace 插件常用的范围。如果您的插件扩展了 Gmail，则必须将所有标记为必需 的范围添加到 Google Workspace 插件清单中。

将宽泛的 https://mail.google.com 范围替换为一组更窄的范围，这些范围允许插件所需的互动。

Google 日历范围

下表列出了扩展 Google 日历的 Google Workspace 插件常用的范围。

Google Chat 范围

如需调用 Google Chat API，请以 Google Chat 用户或以 Google Chat 应用的身份进行身份验证。 每种身份验证类型都需要不同的范围，并且并非所有 Chat API 方法都支持应用身份验证。

如需详细了解 Chat 范围和身份验证类型，请参阅 Chat API 身份验证和授权概览

下表显示了基于支持的身份验证类型的常用 Chat API 方法和范围：

Google 云端硬盘范围

下表列出了扩展 Google 云端硬盘的 Google Workspace 插件常用的范围。

访问令牌

为了保护用户数据，Google Workspace 插件中使用的 Gmail 范围授予对用户数据的临时访问权限。如需启用临时 访问权限，请使用操作事件对象中的 访问令牌调用 GmailApp.setCurrentMessageAccessToken。

启用 Gmail 范围的访问令牌与 ScriptApp.getOAuthToken 返回的访问令牌不同。请使用操作事件对象中提供的令牌。

以下示例展示了如何设置访问令牌以允许访问邮件的元数据。此示例中唯一需要的范围是 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 脚本服务，则可能需要其他范围。在大多数情况下，Apps 脚本会检测到这些范围并自动更新清单。修改清单的范围列表时，请勿移除任何范围，除非您将其替换为更窄的替代范围。

下表显示了 Google Workspace 插件经常使用的范围：