访问和处理脚本发布和触发器。此类允许用户创建脚本触发器并控制将脚本作为服务发布的行为。
属性
媒体资源 | 类型 | 说明 |
---|---|---|
AuthMode | AuthMode | 一个枚举,用于标识 Apps 脚本可以通过触发的函数执行哪些类别的授权服务。 |
AuthorizationStatus | AuthorizationStatus | 用于表示脚本的授权状态的枚举。 |
EventType | EventType | 表示触发的事件类型的枚举。 |
InstallationSource | InstallationSource | 一个枚举,表示脚本是如何作为插件安装给用户的。 |
TriggerSource | TriggerSource | 一个枚举,用于表示导致触发器触发的事件的来源。 |
WeekDay | Weekday | 表示星期几的枚举。 |
方法
方法 | 返回类型 | 简介 |
---|---|---|
deleteTrigger(trigger) | void | 移除指定的触发器,使其不再运行。 |
getAuthorizationInfo(authMode) | AuthorizationInfo | 获取一个对象,用于确定用户是否需要授权此脚本使用一项或多项服务,并提供授权对话框的网址。 |
getIdentityToken() | String | 如果已授予 openid 范围,则获取有效用户的 OpenID Connect 身份令牌。 |
getInstallationSource() | InstallationSource | 返回一个枚举值,指示该脚本如何作为插件提供给当前用户(例如,用户是否通过 Chrome 应用商店自行安装,或者网域管理员是否为所有用户安装了该脚本)。 |
getOAuthToken() | String | 获取有效用户的 OAuth 2.0 访问令牌。 |
getProjectTriggers() | Trigger[] | 获取与当前项目和当前用户关联的所有可安装触发器。 |
getScriptId() | String | 获取脚本项目的唯一 ID。 |
getService() | Service | 获取一个对象,用于控制将脚本发布为 Web 应用。 |
getUserTriggers(document) | Trigger[] | 在给定文档中,获取此用户拥有的所有可安装触发器(仅针对此脚本或插件)。 |
getUserTriggers(form) | Trigger[] | 仅针对此脚本或插件,以给定的形式获取此用户拥有的所有可安装触发器。 |
getUserTriggers(spreadsheet) | Trigger[] | 在指定电子表格中获取此用户拥有的所有可安装触发器(仅针对此脚本或插件)。 |
invalidateAuth() | void | 使有效用户拥有执行当前脚本的授权失效。 |
newStateToken() | StateTokenBuilder | 为可用于回调 API(如 OAuth 流程)的状态令牌创建构建器。 |
newTrigger(functionName) | TriggerBuilder | 开始创建可安装的触发器,该触发器在触发时会调用指定函数。 |
详细文档
deleteTrigger(trigger)
移除指定的触发器,使其不再运行。
// Deletes all triggers in the current project. var triggers = ScriptApp.getProjectTriggers(); for (var i = 0; i < triggers.length; i++) { ScriptApp.deleteTrigger(triggers[i]); }
参数
名称 | 类型 | 说明 |
---|---|---|
trigger | Trigger | 要删除的触发器。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/script.scriptapp
getAuthorizationInfo(authMode)
获取一个对象,用于确定用户是否需要授权此脚本使用一项或多项服务,并提供授权对话框的网址。如果脚本是作为使用可安装触发器的插件发布的,则此信息可用于控制对用户缺少必要授权的代码段的访问。或者,该插件可以要求用户打开授权对话框的网址来解决问题。
var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL); status = authInfo.getAuthorizationStatus(); url = authInfo.getAuthorizationUrl();
参数
名称 | 类型 | 说明 |
---|---|---|
authMode | AuthMode | 请求授权信息的授权模式;在几乎所有情况下,authMode 的值都应该为 ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL) ,因为任何其他授权模式都不需要用户授权 |
弃踢回攻
AuthorizationInfo
- 一个对象,可以提供有关用户授权状态的信息
getIdentityToken()
如果已授予 openid
范围,则获取有效用户的 OpenID Connect 身份令牌。默认情况下,不包含此范围,您必须在清单文件中将其添加为显式范围才能请求此范围。添加范围 https://www.googleapis.com/auth/userinfo.email
或 https://www.googleapis.com/auth/userinfo.profile
即可在令牌中返回其他用户信息。
返回的 ID 令牌是一个编码的 JSON 网络令牌 (JWT),必须对其进行解码才能从中提取信息。以下示例展示了如何解码令牌并提取有效用户的 Google 个人资料 ID。
var idToken = ScriptApp.getIdentityToken(); var body = idToken.split('.')[1]; var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString(); var payload = JSON.parse(decoded); var profileId = payload.sub; Logger.log('Profile ID: ' + profileId);如需查看返回的字段(声明)的完整列表,请参阅 OpenID Connect 文档。
弃踢回攻
String
- 身份令牌(如果有);否则为 null
。
getInstallationSource()
返回一个枚举值,指示该脚本如何作为插件提供给当前用户(例如,用户是否通过 Chrome 应用商店自行安装,或者网域管理员是否为所有用户安装了该脚本)。
弃踢回攻
InstallationSource
- 安装来源。
getOAuthToken()
获取有效用户的 OAuth 2.0 访问令牌。如果脚本的 OAuth 范围足以授权其他通常需要自己的 OAuth 流程的 Google API(如 Google Picker),脚本可以改为传递此令牌来绕过第二个授权提示。令牌会在一段时间(至少几分钟)后过期;脚本应处理授权失败并在需要时调用此方法来获取新的令牌。
此方法返回的令牌仅包含脚本当前所需的范围。之前已获授权但脚本不再使用的范围不会包含在返回的令牌中。如果除了脚本本身需要的范围之外,您还需要其他 OAuth 范围,可以在脚本的清单文件中指定这些范围。
弃踢回攻
String
- OAuth 2.0 令牌的字符串表示法。
getProjectTriggers()
getScriptId()
获取脚本项目的唯一 ID。这是获取脚本项目的唯一标识符(而不是
)的首选方法。此 ID 可用于之前提供项目密钥的所有位置。getProjectKey()
弃踢回攻
String
- 脚本项目的 ID。
getService()
获取一个对象,用于控制将脚本发布为 Web 应用。
// Get the URL of the published web app. var url = ScriptApp.getService().getUrl();
弃踢回攻
Service
- 一个用于观察和控制将脚本发布为 Web 应用的对象。
getUserTriggers(document)
在给定文档中,获取此用户拥有的所有可安装触发器(仅针对此脚本或插件)。此方法不能用于查看附加到其他脚本的触发器。
var doc = DocumentApp.getActiveDocument(); var triggers = ScriptApp.getUserTriggers(doc); // Log the handler function for the first trigger in the array. Logger.log(triggers[0].getHandlerFunction());
参数
名称 | 类型 | 说明 |
---|---|---|
document | Document | 可能包含可安装的触发器的 Google 文档文件。 |
弃踢回攻
Trigger[]
- 给定文档中此用户拥有的触发器数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/script.scriptapp
getUserTriggers(form)
仅针对此脚本或插件,以给定的形式获取此用户拥有的所有可安装触发器。此方法不能用于查看附加到其他脚本的触发器。
var form = FormApp.getActiveForm(); var triggers = ScriptApp.getUserTriggers(form); // Log the trigger source for the first trigger in the array. Logger.log(triggers[0].getTriggerSource());
参数
名称 | 类型 | 说明 |
---|---|---|
form | Form | 可能包含可安装的触发器的 Google 表单文件。 |
弃踢回攻
Trigger[]
- 该用户以给定表单拥有的触发器数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/script.scriptapp
getUserTriggers(spreadsheet)
在指定电子表格中获取此用户拥有的所有可安装触发器(仅针对此脚本或插件)。此方法不能用于查看附加到其他脚本的触发器。
var ss = SpreadsheetApp.getActiveSpreadsheet(); var triggers = ScriptApp.getUserTriggers(ss); // Log the event type for the first trigger in the array. Logger.log(triggers[0].getEventType());
参数
名称 | 类型 | 说明 |
---|---|---|
spreadsheet | Spreadsheet | 可能包含可安装的触发器的 Google 表格文件。 |
弃踢回攻
Trigger[]
- 给定电子表格中该用户拥有的触发器数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/script.scriptapp
invalidateAuth()
使有效用户拥有执行当前脚本的授权失效。用于使当前脚本的所有权限失效。这对于标记为一次性授权的函数尤其有用。由于单次授权函数只能在脚本获得授权后首次运行时调用,因此如果您想在之后执行某项操作,则必须撤消该脚本拥有的所有授权,以便用户能够再次看到授权对话框。
ScriptApp.invalidateAuth();
抛出
Error
- 失效失败时
newStateToken()
为可用于回调 API(如 OAuth 流程)的状态令牌创建构建器。
// Generate a callback URL, given the name of a callback function. The script does not need to // be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL. function getCallbackURL(callbackFunction) { // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end. var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz'; var urlSuffix = '/usercallback?state='; var stateToken = ScriptApp.newStateToken() .withMethod(callbackFunction) .withTimeout(120) .createToken(); return scriptUrl + urlSuffix + stateToken; }
在大多数 OAuth2 流程中,state
令牌会直接传递给授权端点(而不是作为回调网址的一部分),授权端点随后将其作为回调网址的一部分传递。
例如:
- 脚本将用户重定向到 OAuth2 授权网址:
https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
- 用户点击“授权”,OAuth2 授权页面会将用户重定向回
https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
- 上述重定向(返回
http://script.google.com/...
)会导致浏览器向/usercallback
发出请求,而后者会调用StateTokenBuilder.withMethod(method)
指定的方法。
弃踢回攻
StateTokenBuilder
- 用于继续构建状态令牌的对象。
newTrigger(functionName)
开始创建可安装的触发器,该触发器在触发时会调用指定函数。
// Creates an edit trigger for a spreadsheet identified by ID. ScriptApp.newTrigger('myFunction') .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3') .onEdit() .create();
参数
名称 | 类型 | 说明 |
---|---|---|
functionName | String | 在触发器触发时调用的函数。您可以使用所含库中的函数,例如 Library.libFunction1 。 |
弃踢回攻
TriggerBuilder
- 用于继续触发器构建流程的对象。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/script.scriptapp