Method: scripts.run

在 Apps 脚本项目中运行函数。必须部署脚本项目，以便与 Apps 脚本 API 搭配使用，并且调用应用必须共享同一 Cloud Platform 项目。

此方法需要使用 OAuth 2.0 令牌进行授权，该令牌至少包含授权部分中列出的一个范围；不需要授权的脚本项目无法通过此 API 执行。如需查找要包含在身份验证令牌中的正确范围，请打开脚本项目的概览页面，然后向下滚动到“项目 OAuth 范围”。

错误 403, PERMISSION_DENIED: The caller does not have permission 表示用于授权请求的 Cloud Platform 项目与脚本使用的项目不同。

HTTP 请求

POST https://script.googleapis.com/v1/scripts/{deploymentId}:run

网址采用 gRPC 转码语法。

路径参数

参数
deploymentId

string

API 可执行文件部署的部署 ID。在脚本编辑器中，依次点击部署 > 管理部署，然后找到部署 ID。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
字段
function

string

要在指定脚本中执行的函数的名称。该名称不包含圆括号或参数。它可以引用包含的库（例如 Library.libFunction1）中的函数。
parameters[]

value (Value format)

要传递给正在执行的函数的参数。每个形参的对象类型应与 Apps 脚本中的预期类型一致。参数不能是特定于 Apps 脚本的对象类型（例如 Document 或 Calendar）；它们只能是原始类型，例如 string、number、array、object 或 boolean。可选。
sessionState

string

已弃用。仅适用于 Android 插件。一个 ID，用于表示用户在 Google 文档或 Google 表格 Android 应用中的当前会话，作为额外数据包含在启动插件的 Intent 中。当 Android 加载项以会话状态运行时，它会获得绑定脚本的权限，也就是说，它可以访问用户当前的光标位置（在 Google 文档中）或所选单元格（在 Google 表格中）等信息。如需检索状态，请调用 Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState")。可选。
devMode

boolean

如果 true 且用户是脚本的所有者，则脚本会以最近保存的版本运行，而不是以部署的版本运行，以便与 Apps Script API 搭配使用。可选；默认值为 false。

响应正文

如果成功，响应正文将包含结构如下的数据：

以 run 开头的 Apps 脚本函数执行的表示形式。执行响应会在函数完成执行后才会到达。执行运行时长上限列在 Apps 脚本配额指南中。

执行开始后，可能会出现以下四种结果之一：

  • 如果脚本函数成功返回，则 response 字段包含一个 ExecutionResponse 对象，该对象的 result 字段中包含函数的返回值。
  • 如果脚本函数（或 Apps 脚本本身）抛出异常，则 error 字段包含 Status 对象。Status 对象的 details 字段包含一个数组，其中包含一个 ExecutionError 对象，用于提供有关错误性质的信息。
  • 如果执行尚未完成，则 done 字段为 false，并且不存在 response 和 error 字段。
  • 如果 run 调用本身失败（例如，由于请求格式有误或出现授权错误），该方法会返回 4XX 范围内的 HTTP 响应代码，并且响应正文的格式不同。客户端库会自动将 4XX 响应转换为异常类。

JSON 表示法 
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
字段
done

boolean

此字段用于指示脚本执行是否已完成。已完成的执行会填充 response 字段，其中包含已执行函数的 ExecutionResponse。
联合字段 result。操作结果，可以是 error，也可以是有效的 response。如果 done == false，则既不会设置 error，也不会设置 response。如果 done == true，则只能设置 error 或 response 中的一项。部分服务可能不会提供结果。result 只能是下列其中一项：
error

object (Status)

如果 run 调用成功，但脚本函数（或 Apps 脚本本身）抛出异常，则此字段包含 Status 对象。Status 对象的 details 字段包含一个数组，其中包含一个 ExecutionError 对象，用于提供有关错误性质的信息。
response

object

如果脚本函数成功返回，此字段将包含一个 ExecutionResponse 对象，其中包含函数的返回值。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

授权范围

需要以下 OAuth 范围之一：

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

如需了解详情，请参阅 OAuth 2.0 概览。

状态

如果 run 调用成功，但脚本函数（或 Apps 脚本本身）抛出异常，则响应正文的 error 字段包含此 Status 对象。

JSON 表示法 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
字段
code

integer

状态代码。对于此 API，此值可以是：

  • 10，表示 SCRIPT_TIMEOUT 错误，
  • 3，表示 INVALID_ARGUMENT 错误；或者
  • 1，表示 CANCELLED 执行。
message

string

面向开发者的错误消息（采用英语）。任何向用户显示的错误消息都应进行本地化并通过 details 字段发送，或者由客户端进行本地化。
details[]

object

一个数组，包含一个 ExecutionError 对象，用于提供有关错误性质的信息。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。