对许多基于 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
,请尝试以下操作:
- 打开插件的 Apps 脚本项目,然后找到
onOpen()
函数。 - 搜索
onOpen()
函数,看看是否提及 Apps 脚本 与其关联的服务或对象,例如PropertiesService
、SpreadsheetApp
或GmailApp
。 - 如果某个服务仅用于创建界面元素,
将其移除或将其封装在注释块中。
仅保留以下方法:
.getUi()
、.createMenu()
、.addItem()
和.addToUi()
。 此外,您还可以查找并移除函数之外的服务。 - 找出可能包含注释或移除的代码行的函数 尤其是那些使用所生成信息的用户, 并将服务调用移至需要它们的函数。重新排列或重写 以适应前面步骤中所做的更改。
保存代码并创建测试部署。
创建测试部署时,请确保 Config 字段 是为当前用户安装,并且配置框下方的文本显示 在
AuthMode.None
中测试启动测试部署并打开扩展程序菜单。
如果显示了所有菜单项,则表明问题已解决。 如果您只看到帮助菜单,请返回第 1 步。 您可能错过了服务呼叫。