编辑器插件授权

对许多基于 Apps 脚本的应用进行授权非常简单，因为 当有人尝试访问脚本项目时，脚本项目会请求获取所需的所有权限 使用。

以下各项的授权模式： 编辑器插件是 变得更加复杂：

  • 当用户创建文件时，该用户安装的所有插件 扩展程序菜单中均列有相应列表，即使 如果用户尚未授权这些插件，则会发生该错误。

  • 这些插件适用于 可与协作者共享的 Google 云端硬盘。不参与 已安装编辑器插件，可在文档中查看 文件创建者使用它的位置

  • 编辑器插件会自动运行其 onOpen() 函数。

为保护用户数据，采用的授权模式会使某些服务 onOpen()无法使用。本指南有助于您了解自己的代码 可以执行的操作和时间。

授权模型

编辑器插件的授权模式取决于 其状态（取决于使用者：安装了此插件的用户） 或协作者。

编辑器插件状态

扩展程序菜单中的编辑器插件 已安装和/或已启用

  • 安装了适用于特定操作系统的 用户或其管理员从 Google Workspace Marketplace，并授权其访问用户的 Google 数据。
  • 插件已在文档、表单、 或电子表格。
  • 有人协同处理文件，并且其中一人使用 插件，也就是为单个用户安装的，而 enabled。

下表总结了已安装版本与已启用版本之间的不同。 请注意，当您 以插件形式测试脚本 则可以在这两种状态下之一或全部运行测试

已安装 已启用
适用对象 用户 文档、表单、演示文稿或电子表格
原因 从商店获取插件 使用 时从商店获取插件 该文档、表单、演示文稿或电子表格，或者
在该环境中使用以前安装的插件 文档、表单、演示文稿或电子表格
菜单公开范围 在所有文档、表单、演示文稿 或他们打开或创建的电子表格 文档、表单、演示文稿 或电子表格
onOpen() 的授权模式 AuthMode.NONE（
） （除非也启用了，在这种情况下， AuthMode.LIMITED)		 AuthMode.LIMITED

授权模式

编辑器插件的 onOpen() 函数运行 在用户打开文档、表单、演示文稿或电子表格时触发。 为了保护用户的Apps 脚本会限制 onOpen() 函数的用途。编辑器插件状态 决定了 onOpen() 函数在哪种授权模式下运行。

如果文件中的某个编辑器插件已启用， 表单、演示文稿或电子表格，onOpen()会在 AuthMode.LIMITED。如果该插件未启用且处于 仅已安装，onOpen() 在 AuthMode.NONE 中运行。

在 AuthMode.NONE 中，插件无法运行某些 直到用户与该插件互动 点击或运行自定义函数。如果您的 插件尝试在 onOpen() 中使用这些服务， onInstall() 或全局范围，则权限失败和其他调用（如 填写菜单，停止。“帮助”是唯一受支持的选项。

如需运行受限服务调用，您必须使用 AuthMode.FULL 授权 模式。用户互动功能，例如点击菜单选项 只在此模式下运行。在 AuthMode.FULL 模式下运行代码后， 插件可以使用用户授权的所有范围。

Apps 脚本通过了授权模式 作为 Apps 脚本的 authMode 属性 事件参数，e；值 e.authMode 对应于 Apps 脚本中的一个常量 ScriptApp.AuthMode 枚举。

授权模式适用于所有 Apps 脚本执行方法， 包括从脚本编辑器、菜单项或从 Apps 脚本运行 google.script.run 调用。不过， 只有在脚本作为结果运行时才能检查 e.authMode 属性 （例如 onOpen()、onEdit()）的触发器 或 onInstall()。自定义函数 在 Google 表格中使用自己的授权模式 AuthMode.CUSTOM_FUNCTION， 它与 LIMITED 类似，但限制略有不同。所有角色 在其他情况下，脚本在 AuthMode.FULL 中运行，具体如下文所述 表格。

NONE LIMITED CUSTOM_FUNCTION FULL
出现于 onOpen()（如果用户已安装 但没有在文档、表单 演示文稿或电子表格） onOpen()（所有其他时间）
onEdit()（仅适用于 Google 表格）		 自定义函数 所有其他时间，包括：
可安装的触发器
onInstall()
google.script.run
访问用户数据 仅限语言区域 仅限语言区域 仅限语言区域 是
访问文档、表单、演示文稿或电子表格 否 是 是 - 只读 是
访问界面 添加菜单项 添加菜单项 否 是
可使用 Properties 否 是 是 是
Jdbc、UrlFetch的访问权限 否 否 是 是
其他服务 Logger
Utilities		 不访问用户数据的任何服务 不访问用户数据的任何服务 所有服务

编辑器插件的授权生命周期

为当前用户安装了插件时 或是在当前文件中启用的 加载了以下插件：文档、表单、演示文稿 或电子表格该插件为 Extensions 菜单中所列扩展程序并开始监听 简单触发器 onInstall()， onOpen()和onEdit()。如果用户点击 扩展程序菜单项，则它会运行。

已安装编辑器插件

从应用店安装编辑器插件后， onInstall() 函数在 AuthMode.FULL 中运行。在此授权模式下， 插件可以运行复杂的设置例程。您还应该 使用 onInstall() 创建菜单项，因为文档、表单、演示文稿、 或电子表格已打开，但 onOpen() 函数尚未运行。 以下示例展示了如何调用 onOpen() 函数 从 onInstall() 函数：

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

编辑器插件已打开

当文档、表单、演示文稿或电子表格打开时 当前用户已安装的编辑器插件或 所有协作者在文件中已启用的功能，并调用 onOpen() 函数。onOpen() 取决于某个插件 已安装或已启用。

如果插件仅创建基本菜单，则模式 没关系。以下示例展示了一个基本的 onOpen() 函数：

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

根据存储的 Apps 脚本添加动态菜单项 属性，用于读取 文件，或要执行其他高级任务， 必须识别授权模式并进行适当处理。

以下示例展示了一个高级 onOpen() 函数，该函数可更改其 根据授权模式执行下列操作：

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

请注意，在 AuthMode.LIMITED。您可以使用菜单项 以打开边栏和对话框，因为这些在 AuthMode.FULL 中运行。

用户运行编辑器插件

当用户点击扩展程序菜单项时， Apps 脚本首先会检查用户是否安装了 插件，以及 否则就会提示他们执行这些操作如果用户已向 此脚本会运行 对应于 AuthMode.FULL 中的菜单项。通过 文档、表单、 或电子表格（如果尚未创建的话）

排查插件菜单无法呈现的问题

如果您的代码 未正确管理授权模式。例如：

  • 插件尝试运行 Apps 脚本 当前授权模式不支持的服务。

  • 插件尝试在用户之前运行服务调用 会与之互动

要移除或重新排列导致以下项目中存在的权限错误的服务调用， AuthMode.NONE，请尝试以下操作：

  1. 打开插件的 Apps 脚本项目，然后找到 onOpen() 函数。
  2. 搜索 onOpen() 函数，看看是否提及 Apps 脚本 与其关联的服务或对象，例如 PropertiesService、SpreadsheetApp 或 GmailApp。
  3. 如果某个服务仅用于创建界面元素， 将其移除或将其封装在注释块中。 仅保留以下方法：.getUi()、.createMenu()、.addItem() 和 .addToUi()。 此外，您还可以查找并移除函数之外的服务。
  4. 找出可能包含注释或移除的代码行的函数 尤其是那些使用所生成信息的用户， 并将服务调用移至需要它们的函数。重新排列或重写 以适应前面步骤中所做的更改。

  5. 保存代码并创建测试部署。

    创建测试部署时，请确保 Config 字段 是为当前用户安装，并且配置框下方的文本显示 在 AuthMode.None 中测试

  6. 启动测试部署并打开扩展程序菜单。

  7. 如果显示了所有菜单项，则表明问题已经解决。 如果您只看到帮助菜单，请返回第 1 步。 您可能错过了服务呼叫。