Class ScriptApp

ScriptApp

访问和操纵脚本发布和触发器。这个类允许用户创建脚本 触发器和控制脚本作为服务发布。

属性

属性类型说明
AuthModeAuthMode一个枚举，用于标识 Apps 脚本能够执行哪些类别的授权服务 通过触发的函数执行。
AuthorizationStatusAuthorizationStatus表示脚本授权状态的枚举。
EventTypeEventType一个枚举，用于表示所触发的事件类型。
InstallationSourceInstallationSource一个枚举，指示如何将脚本作为插件安装到用户。
TriggerSourceTriggerSource一个枚举，用于表示导致触发器触发的事件的来源。
WeekDayWeekday表示星期几的枚举。

方法

方法返回类型简介
deleteTrigger(trigger)void移除指定的触发器，使其不再运行。
getAuthorizationInfo(authMode)AuthorizationInfo获取一个对象，该对象用于确定用户需要授权此脚本使用某个 以及提供授权对话框的网址。
getIdentityToken()String获取 OpenID Connect 身份令牌， 有效用户（如果已授予 openid 范围）。
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 Connect 身份令牌， 有效用户（如果已授予 openid 范围）。不包含此范围 默认情况下，您必须在清单中将其作为显式范围添加 请求该文件。添加范围 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 选择器），脚本可以绕过 改为传递此令牌来触发第二个授权提示。令牌会在一段时间（ 至少几分钟）；脚本应处理授权失败，并调用此方法 在需要时获取新的令牌。

此方法返回的令牌仅包含脚本当前所需的范围。 之前已获得授权但不再由脚本使用的范围不包含在 返回的令牌。如果需要脚本本身以外的 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

已弃用的方法