范围

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

在此流程中,提示会让用户知道应用想要执行什么操作。例如,插件可能需要读取用户的电子邮件或在其日历中创建活动的权限。插件的脚本项目将这些单独的权限定义为 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 客户端验证,然后才能发布。如需了解详情,请参阅以下指南:

受限范围

某些范围会受到限制,并受有助于保护用户数据的其他规则的约束。如果您打算发布使用一个或多个受限范围的 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

如果插件使用撰写操作触发条件,则是必需的。 允许该插件暂时创建新消息草稿和回复。如需了解详情,请参阅撰写消息草稿;此范围通常也用于撰写操作。需要访问令牌。

读取打开的邮件元数据 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 文档、表格和幻灯片的 Google Workspace 插件的常用范围。

范围
当前文档文件访问权限 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 Script Slides API,则必须提供。 授予对开放式演示文稿的临时访问权限。

文件级访问权限 https://www.googleapis.com/auth/drive.file

插件使用 onFileScopeGrantedTrigger 以及插件访问 Docs、Sheets、Slide 或 Drive REST API 时必须要提供。 使用 Apps 脚本高级云端硬盘服务授予对应用创建或打开的文件的每个文件的访问权限。不过,使用基本云端硬盘服务时无法执行类似的操作。文件授权按文件授予,并在用户向应用取消授权时撤消。

其他范围

如果插件使用其他 Apps 脚本服务,则可能需要额外的范围。在大多数情况下,您可以让 Apps 脚本检测这些范围并自动更新清单。修改清单的范围列表时,请不要移除任何范围,除非您用更合适的替代范围(例如更窄的范围)替换这些范围。

下面列出了通常与 Google Workspace 插件搭配使用的 Apps 脚本范围,供您参考:

范围
读取用户的电子邮件地址 https://www.googleapis.com/auth/userinfo.email

允许项目读取当前用户的电子邮件地址。

允许调用外部服务 https://www.googleapis.com/auth/script.external_request

允许项目发出 UrlFetch 请求。如果项目使用 OAuth2 for Apps Script 库,也必须执行此操作。

读取用户的语言区域和时区 https://www.googleapis.com/auth/script.locale

允许项目了解当前用户的语言区域和时区。 如需了解详情,请参阅访问用户语言区域和时区

创建触发器 https://www.googleapis.com/auth/script.scriptapp

允许项目创建触发器