作用域

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

在此流程中,提示会告知用户应用需要权限执行的操作。例如,插件可能想要读取用户的电子邮件或在其日历中创建活动的权限。该插件的脚本项目将这些权限定义为 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 帐号的完整访问权限。对于已发布的插件,您必须将此范围替换为更受限的集合来满足插件的需求,而不能执行其他操作。

您可以通过修改脚本项目的清单文件来明确设置脚本项目使用的范围。清单字段 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 客户端验证,然后才能发布。如需了解详情,请参阅以下指南:

受限范围

某些范围会受到限制,并受到有助于保护用户数据的额外规则的约束。如果您打算发布使用一个或多个受限范围的 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 清单字段设置为 READREAD_WRITE 时,此数据才可用。

写入用户生成的事件数据 https://www.googleapis.com/auth/calendar.addons.current.event.write

如果插件需要写入用户生成的事件数据,则为必需。 允许该插件修改用户生成的事件数据。只有当 addOns.calendar.eventAccess 清单字段设置为 WRITEREAD_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 插件范围

我们还专门为 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 触发器需要访问元数据,则必须提供此范围。实际上,此范围可让写邮件触发访问回复电子邮件草稿的收件人列表(to:、cc: 和 bcc:)。

阅读打开的邮件内容 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 文档文件访问权限 https://www.googleapis.com/auth/documents.currentonly

如果插件要访问 Apps 脚本文档 API,则必须选择此字段。 授予对已打开文档内容的临时访问权限。

当前 Google 表格文件的访问权限 https://www.googleapis.com/auth/spreadsheets.currentonly

如果该插件访问 Apps Script Tables 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 Workspace 插件搭配使用的 Apps 脚本范围,供您参考:

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