瞄准镜

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

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

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

查看范围

您可以执行 以下：

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

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

设置显式范围

Apps 脚本通过扫描来自动确定脚本需要哪些范围 用于调用需要这些方法的函数调用。对于大多数脚本来说，这是 并节省时间，但对于已发布的插件， 更直接地控制作用域。

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

您可以通过修改 manifest 文件。清单字段 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 客户端验证 然后才能发布如需了解详情，请参阅以下指南：

受限范围

某些范围受到限制，并受到额外规则的约束 保护用户数据如果您打算发布使用 一个或多个受限范围，该插件必须符合 然后才能发布

查看受限范围的完整列表 然后再尝试发布如果您的插件使用上述任何一种协议，您必须遵守 替换为 针对特定 API 范围的其他要求 。

日历范围

以下是可扩展 Google 日历的 Google Workspace 插件的常用范围。

范围
访问事件元数据 https://www.googleapis.com/auth/calendar.addons.execute

如果该插件会访问日历活动元数据，则必须提供此值。允许 用于访问事件元数据的插件。

读取用户生成的事件数据 https://www.googleapis.com/auth/calendar.addons.current.event.read

如果该插件需要读取用户生成的事件数据，则必须提供此值。 允许该插件访问由用户生成的事件数据。这些数据 仅当 <ph type="x-smartling-placeholder"></ph> 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

如果该插件实现了由系统触发上下文界面，则必须提供 当用户选择云端硬盘中的内容时触发。 允许该插件读取有关用户拥有的内容的有限元数据 所选文件。元数据仅限于作品的 ID 标题、MIME 类型、图标网址以及该插件是否有权执行以下操作： 访问该项。

按文件访问 https://www.googleapis.com/auth/drive.file

如果该插件需要访问个人云端硬盘，则推荐使用 文件。 使用 Apps 脚本高级云端硬盘 服务。这不支持使用 基本云端硬盘服务， 但是。文件授权是按文件授予的， 在用户取消对应用的授权后撤消。

请参阅 <ph type="x-smartling-placeholder"></ph> 请求访问所选文件的文件示例。

Gmail 插件范围

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

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

此外，请务必替换您测试中非常宽泛的 https://mail.google.com 范围 范围更小，以允许您的插件与您的插件互动 所需的一切，仅此而已。

范围
创建新草稿 https://www.googleapis.com/auth/gmail.addons.current.action.compose

如果该插件使用 <ph type="x-smartling-placeholder"></ph> 组合操作触发器。 允许该插件临时创建新草稿邮件， 回复。请参阅 撰写邮件草稿 了解详情；该范围通常还用于 <ph type="x-smartling-placeholder"></ph> 撰写操作。 需要访问令牌。

读取打开的邮件的元数据 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 插件权限 临时访问用户数据。要启用临时访问权限，您必须调用 函数 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 Document 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 时必须选中 以及该插件是否访问 Google 文档、表格、幻灯片或 Drive API。 使用 Apps 脚本高级云端硬盘 服务。这不支持使用 基本云端硬盘服务， 但是。文件授权是按文件授予的， 在用户取消对应用的授权时被撤消。

其他范围

如果您的插件使用其他 Apps 脚本服务，则可能需要额外的作用域。 在大多数情况下，您可以让 Apps 脚本检测这些范围并更新 清单。修改清单的范围列表时，请勿移除 除非您要用更合适的替代方法替换它们，否则 例如缩小范围

以下列出了经常用于测试的 Google Apps 脚本范围，供您参考。 与 Google Workspace 插件搭配使用：

范围
读取用户的电子邮件地址 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 应用中插入资源链接。 要了解详情，请参阅 您可以通过“@”菜单创建第三方资源。