范围

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

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

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

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

查看镜重

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

1. 打开脚本项目。
2. 点击左侧的概览 icon。
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 插件常用的镜重范围。

注意：currentonly 范围仅在 Apps 脚本服务中可用。这不包括 Apps 脚本高级服务或对 Google Workspace API 的直接调用。

范围
当前 Google 文档文件访问权限	https://www.googleapis.com/auth/documents.currentonly 如果该插件会访问 Apps Script Docs API，则必须提供此权限。 授予对打开的文档内容的临时访问权限。
当前 Google 表格文件访问权限	https://www.googleapis.com/auth/spreadsheets.currentonly 如果该插件会访问 Apps 脚本 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 如果插件使用 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 Chat 范围

开发者预览版：Google Workspace 开发者预览版计划的一部分，可让您抢先体验某些功能。

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

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

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

方法	支持用户身份验证	支持应用身份验证	支持的授权范围
发送消息			使用用户身份验证： chat.messages.create chat.messages chat.import 使用应用身份验证： chat.bot
创建聊天室			使用用户身份验证： chat.spaces.create chat.spaces chat.import 需要应用身份验证和管理员批准（开发者预览版中提供）： chat.app.spaces.create chat.app.spaces
创建聊天室并向其添加成员		—	使用用户身份验证： chat.spaces.create chat.spaces
向聊天室添加用户			使用用户身份验证： chat.memberships chat.memberships.app chat.import 需要应用身份验证和管理员批准（开发者预览版中提供）： chat.app.memberships
列出 Chat 聊天室中的活动或事件		—	使用用户身份验证时，您必须为请求中包含的每个 事件类型使用一个作用域： 对于与消息相关的事件： chat.messages chat.messages.readonly 对于与回应相关的事件： chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly 对于与会员身份相关的事件： chat.memberships chat.memberships.readonly 对于与聊天室相关的事件： chat.spaces chat.spaces.readonly

Google 云端硬盘范围

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

范围
读取所选内容的元数据	https://www.googleapis.com/auth/drive.addons.metadata.readonly 如果该插件实现了在用户选择云端硬盘中的项时触发的上下文界面，则必须提供此方法。 允许该插件读取有关用户在 Google 云端硬盘中选择的内容的有限元数据。元数据仅限于内容的 ID、标题、MIME 类型、图标网址，以及该插件是否有权访问相应内容。
按文件访问	https://www.googleapis.com/auth/drive.file 如果插件需要访问单个云端硬盘文件，建议使用此权限。 使用 Apps 脚本高级云端硬盘服务，为应用创建或打开的文件授予按文件的访问权限。不过，这不允许使用基本云端硬盘服务执行类似操作。系统会按文件授予文件授权，并会在用户撤消对应用的授权后撤消授权。 请参阅 请求对所选文件的文件访问权限示例。

访问令牌

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

注意 ：启用 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 Script 服务，则可能需要额外的范围。 在大多数情况下，您可以让 Apps Script 检测这些作用域并自动更新清单。修改清单的范围列表时，请勿移除任何范围，除非您要将其替换为更合适的替代项（例如范围更窄的范围）。

下表列出了 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 应用中插入指向该资源的链接。 如需了解详情，请参阅 通过“@”菜单创建第三方资源。