编辑器插件的授权范围

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

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

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

查看镜重

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

  1. 打开脚本项目。
  2. 点击左侧的概览 icon。
  3. 在“Project OAuth Scopes”（项目 OAuth 范围）下查看相应范围。

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

设置显式镜重

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

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

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

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

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

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

  5. 保存清单文件更改。

OAuth 验证

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

受限范围

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

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

编辑器插件作用域

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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