编辑器插件的授权范围

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

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

您可以使用网址字符串在清单中声明范围。在授权流程中，Apps 脚本会向用户显示范围的人类可读说明。例如，您的插件可能会使用“读取当前文档”范围，该范围在清单中写为 https://www.googleapis.com/auth/documents.currentonly。在授权流程中，具有此范围的插件会要求用户允许该插件执行以下操作：查看和管理已安装此应用的文档。

查看范围

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

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

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

设置明确的范围

Apps 脚本会扫描脚本的代码，查找需要范围的函数调用，从而自动确定脚本需要哪些范围。对于大多数脚本，这已足够，并且可以节省您的时间，但对于已发布的插件，您应更直接地控制范围。

例如，Apps 脚本可能会默认向插件脚本项目授予非常宽松的范围 https://mail.google.com。当用户授权具有此范围的脚本项目时，该项目会被授予对用户 Gmail 账号的完全访问权限。对于已发布的插件，您必须将此范围替换为一组更有限的范围，这些范围应涵盖插件的需求，但不能超出此范围。

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

  1. 查看您的插件目前使用的范围。确定需要做出哪些更改，例如使用更窄的范围。
  2. 打开插件的清单文件。
  3. 找到标记为 oauthScopes 的顶级字段。如果不存在，您可以添加。

  4. oauthScopes 字段指定一个字符串数组。如需设置项目使用的范围，请将此数组的内容替换为您希望项目使用的范围。 例如，对于扩展 Google 表格的编辑器插件，您可能需要以下权限：

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}

  5. 保存清单文件更改。

OAuth 验证

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

受限范围

某些范围是受限的，并受有助于保护用户数据的其他规则的约束。如果您打算发布使用一个或多个受限范围的 Gmail 或编辑器插件，则该插件必须符合所有指定的限制，然后才能发布。

在尝试发布之前，请先查看受限范围的完整列表。如果您的插件使用了其中任何一项，您必须在发布之前遵守特定 API 范围的其他要求。

适用于 Visual Studio Code 的 Google Workspace 开发者工具扩展程序可提供所有范围的诊断信息，包括范围的说明以及该范围是否敏感或受限。

编辑器插件范围

构建编辑器插件时，所需的范围由插件代码使用的 Apps 脚本服务和方法决定。例如，Google 表格插件可能需要 https://www.googleapis.com/auth/spreadsheets.readonly 范围才能从不同的 Google 表格中读取信息。

当您向脚本项目添加代码时，Apps 脚本会自动确定您使用的服务所需的范围。对于编辑器插件，您通常只需依赖此自动范围收集功能，而无需自行确定范围并明确设置它们。

如果您未明确设置范围，并且编辑器插件仅读取或写入打开的编辑器文件，请将以下注释添加到您的某个脚本项目文件中：

  /**
   * @OnlyCurrentDoc
   */

此注释会告知 Apps 脚本将设置的编辑器文件范围缩小为 currentonly。例如，如果您将此注释添加到 Google 表格插件脚本项目文件中，则表示该插件只需要对当前打开的表格进行操作的权限，而不需要对用户可能在 Google 云端硬盘中拥有的任何其他表格进行操作的权限。反之，如果您的 Google 表格插件需要读取或写入用户当前未打开的表格中的数据，则不应使用此注释。