此页面由 Cloud Translation API 翻译。

范围

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

在此流程中，提示会告诉用户应用需要什么权限。例如，某个插件可能想要获取用户的电子邮件消息，或在日历中创建活动。插件的脚本项目将这些各个权限定义为 OAuth 范围。

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

查看范围

您可以执行以下：

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

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

设置显式范围

Apps 脚本通过扫描来自动确定脚本需要哪些范围用于调用需要这些方法的函数调用。对于大多数脚本，这已足够，并且可以节省时间，但对于已发布的插件，您应更直接地控制镜重。

例如，Apps Script 可能会默认向插件脚本项目授予极其宽松的范围 https://mail.google.com。当用户向脚本授权时项目具有对用户 Gmail 的完整访问权限。对于已发布的插件，您必须将此范围替换为仅涵盖插件需求的更有限的范围。

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

查看您的插件当前使用的权限范围。确定需要进行哪些更改，例如使用更窄的范围。
打开插件的清单文件。
找到标记为 oauthScopes 的顶级字段。如果不存在就可以添加它了
oauthScopes 字段指定字符串数组。如需设置项目使用的镜重，请将此数组的内容替换为您希望项目使用的镜重。例如，对于扩展 Gmail 的 Google Workspace 插件，您可能需要提供以下信息：
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
保存对清单文件所做的更改。

OAuth 验证

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

受限范围

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

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

日历范围

以下是可扩展 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` 如果该插件需要写入用户生成的事件数据，则必须提供此值。允许该插件修改由用户生成的事件数据。这些数据仅当 <ph type="x-smartling-placeholder"></ph> `addOns.calendar.eventAccess` 清单字段设置为 `WRITE` 或 `READ_WRITE`。

云端硬盘范围

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

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

Gmail 插件范围

有几个范围是专为有助于保护用户 Gmail 的 Google Workspace 插件数据。您必须明确添加这些范围以及用来创建您的插件的所有其他文件。

以下是可扩展 Gmail 的 Google Workspace 插件的常用范围：必须将标记为必需的变量添加到 Google Workspace 插件清单（如果您的插件扩展） Gmail。

此外，请务必替换您测试中非常宽泛的 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 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 文档、表格和幻灯片。

范围
当前 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 ScriptSlide API，则必须提供此值。授予对打开的演示文稿内容的临时访问权限。
按文件访问	`https://www.googleapis.com/auth/drive.file` 如果插件要使用 `onFileScopeGrantedTrigger` 且要访问文档、表格、幻灯片或云端硬盘 API，则必须提供此权限。使用 Apps 脚本高级云端硬盘服务。这不支持使用基本云端硬盘服务，但是。文件授权是按文件授予的，当用户撤消对应用的授权时，系统会撤消相应文件的授权。

其他镜重

如果您的插件使用其他 Apps Script 服务，则可能需要其他范围。在大多数情况下，您可以让 Apps Script 检测这些作用域并自动更新清单。修改清单的范围列表时，请勿移除任何范围，除非您要将其替换为更合适的替代项（例如范围更窄的范围）。

下面列出了常与 Google Workspace 插件搭配使用的 Apps 脚本作用域，供您参考：

范围
读取用户的电子邮件地址	`https://www.googleapis.com/auth/userinfo.email` 允许项目读取当前用户的电子邮件地址。
允许调用外部服务	`https://www.googleapis.com/auth/script.external_request` 允许项目 `UrlFetch` 请求。如果项目使用 <ph type="x-smartling-placeholder"></ph> 适用于 Apps 脚本的 OAuth2 库。
读取用户的语言区域和时区	`https://www.googleapis.com/auth/script.locale` 允许项目了解当前用户的语言区域和时区。请参阅访问用户语言区域和时区可了解详情。
创建触发器	`https://www.googleapis.com/auth/script.scriptapp` 允许项目创建 <ph type="x-smartling-placeholder"></ph> 触发器。
预览第三方链接	`https://www.googleapis.com/auth/workspace.linkpreview` 如果插件预览链接来自第三方服务，则此字段是必需的。允许项目在用户与 Google Workspace 应用互动时查看应用内的链接。要了解详情，请参阅使用智能条状标签预览链接。
创建第三方资源	`https://www.googleapis.com/auth/workspace.linkcreate` 如果该插件在第三方服务中创建资源，则必须提供此值。允许项目读取用户提交到资源创建表单在 Google Workspace 应用中插入资源链接。如需了解详情，请参阅通过“@”菜单创建第三方资源。