Class ScriptApp

脚本应用

访问和操作脚本发布和触发器。借助此类，用户可以创建脚本触发器，并控制将脚本作为服务发布。

属性

属性类型说明
AuthModeAuthMode一个枚举，用于标识 Apps Script 能够通过触发的函数执行哪些类别的已获授权服务。
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.
const triggers = ScriptApp.getProjectTriggers();
for (let 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 Web 令牌 (JWT)，必须对其进行解码才能从中提取信息。以下示例展示了如何解码令牌并提取有效用户的 Google 个人资料 ID。 

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);
如需查看返回的字段（声明）的完整列表，请参阅 OpenID Connect 文档。

返回

String - 身份令牌（如果有）；否则为 null。

getInstallationSource()

返回一个枚举值，用于指明脚本是如何作为插件安装给当前用户的（例如，用户是通过 Chrome 网上应用店自行安装的，还是域名管理员为所有用户安装的）。

返回

InstallationSource - 安装来源。

getOAuthToken()

获取有效用户的 OAuth 2.0 访问令牌。如果脚本的 OAuth 范围足以授权通常需要使用自己的 OAuth 流程的其他 Google API（例如 Google Picker），则脚本可以改为传递此令牌，从而绕过第二次授权提示。令牌会在一段时间（至少几分钟）后过期；脚本应处理授权失败，并在需要时调用此方法以获取新的令牌。

此方法返回的令牌仅包含脚本当前需要的范围。返回的令牌中不包含之前已获授权但脚本不再使用的范围。如果除了脚本本身所需的 OAuth 范围之外，还需要其他 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.
const url = ScriptApp.getService().getUrl();

返回

Service - 用于观察和控制将脚本发布为 Web 应用的对象。

getUserTriggers(document)

仅针对此脚本或插件，获取给定文档中此用户拥有的所有可安装触发器。此方法无法用于查看附加到其他脚本的触发器。 

const doc = DocumentApp.getActiveDocument();
const 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)

获取给定表单中此用户拥有的所有可安装触发器，仅限此脚本或插件。此方法无法用于查看附加到其他脚本的触发器。 

const form = FormApp.getActiveForm();
const 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)

仅针对此脚本或插件，获取给定电子表格中此用户拥有的所有可安装触发器。此方法无法用于查看附加到其他脚本的触发器。 

const ss = SpreadsheetApp.getActiveSpreadsheet();
const 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.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const 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

已弃用的方法