范围

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

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

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

查看镜重

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

1. 打开脚本项目。
2. 点击左侧的概览 iconinfo_outline。
3. 在“Project OAuth Scopes”（项目 OAuth 范围）下查看相应范围。

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

设置显式镜重

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

例如，Apps Script 可能会默认为插件脚本项目授予非常宽松的范围 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 Script 的 OAuth 客户端验证
• 未验证的应用
• OAuth 验证常见问题解答
• Google API 服务：用户数据政策

受限范围

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

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

为 Google Workspace 插件选择镜重

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

编辑器镜重

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

Gmail

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

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

此外，请务必将您的插件中非常宽泛的 https://mail.google.com 范围替换为一组更窄的范围，以允许您的插件进行所需的互动，但不允许进行其他互动。

Google 日历镜重

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

Google Chat 范围

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

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

下表根据支持的身份验证类型显示了常用的 Chat API 方法和镜重：

Google 云端硬盘范围

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

访问令牌

为保护用户数据，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 Script 检测这些作用域并自动更新清单。修改清单的范围列表时，请勿移除任何范围，除非您要将其替换为更合适的替代项（例如范围更窄的范围）。

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