范围

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

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

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

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

查看范围

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

1. 打开脚本项目。
2. 点击左侧的概览图标 。
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 文档、表格和幻灯片的 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 并且访问 Google 文档、表格、幻灯片或云端硬盘 API，则必须声明此权限。 使用 Apps 脚本高级云端硬盘服务，授予对应用创建或打开的文件的单文件访问权限。不过，这不允许使用基本 Drive 服务执行类似操作。文件授权是按文件授予的，当用户取消授权应用时，系统会撤消相应授权。

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 授予对打开的邮件的元数据（例如主题或收件人）的临时访问权限。不允许读取消息内容，并且需要访问令牌。 如果插件在撰写操作触发器中使用元数据，则必须添加此元素。 对于 撰写操作，如果撰写触发器需要访问元数据，则必须使用此范围。实际上，此范围允许撰写触发器访问回复电子邮件草稿的收件人列表（收件人、抄送和密送）。
读取打开的邮件内容	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 范围

如需调用 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 脚本高级云端硬盘服务，授予对应用创建或打开的文件的单文件访问权限。不过，这不允许使用基本 Drive 服务执行类似操作。文件授权是按文件授予的，当用户取消授权应用时，系统会撤消授权。 请参阅 请求访问所选文件的示例。

访问令牌

为了保护用户数据，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 脚本服务，则可能需要其他范围。 在大多数情况下，您可以让 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 应用中插入指向该资源的链接。 如需了解详情，请参阅 通过 @ 菜单创建第三方资源。