Class ScriptApp

ScriptApp

访问和处理脚本发布和触发器。此类允许用户创建脚本触发器并控制将脚本作为服务发布的行为。

属性

媒体资源类型说明
AuthModeAuthMode一个枚举,用于标识 Apps 脚本可以通过触发的函数执行哪些类别的授权服务。
AuthorizationStatusAuthorizationStatus用于表示脚本的授权状态的枚举。
EventTypeEventType表示触发的事件类型的枚举。
InstallationSourceInstallationSource一个枚举,表示脚本是如何作为插件安装给用户的。
TriggerSourceTriggerSource一个枚举,用于表示导致触发器触发的事件的来源。
WeekDayWeekday表示星期几的枚举。

方法

方法返回类型简介
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]);
}

参数

名称类型说明
triggerTrigger要删除的触发器。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

  • https://www.googleapis.com/auth/script.scriptapp

getAuthorizationInfo(authMode)

获取一个对象,用于确定用户是否需要授权此脚本使用一项或多项服务,并提供授权对话框的网址。如果脚本是作为使用可安装触发器插件发布的,则此信息可用于控制对用户缺少必要授权的代码段的访问。或者,该插件可以要求用户打开授权对话框的网址来解决问题。

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

参数

名称类型说明
authModeAuthMode请求授权信息的授权模式;在几乎所有情况下,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()

获取与当前项目和当前用户关联的所有可安装触发器。

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

弃踢回攻

Trigger[] - 与此项目关联的当前用户的触发器数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

  • https://www.googleapis.com/auth/script.scriptapp

getScriptId()

获取脚本项目的唯一 ID。这是获取脚本项目的唯一标识符(而不是 getProjectKey())的首选方法。此 ID 可用于之前提供项目密钥的所有位置。

弃踢回攻

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());

参数

名称类型说明
documentDocument可能包含可安装的触发器的 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());

参数

名称类型说明
formForm可能包含可安装的触发器的 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());

参数

名称类型说明
spreadsheetSpreadsheet可能包含可安装的触发器的 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();

参数

名称类型说明
functionNameString在触发器触发时调用的函数。您可以使用所含库中的函数,例如 Library.libFunction1

弃踢回攻

TriggerBuilder - 用于继续触发器构建流程的对象。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

  • https://www.googleapis.com/auth/script.scriptapp

已废弃的方法