在 Apps 脚本项目中运行函数。必须部署脚本项目以与 Apps Script 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/{scriptId}:run
网址采用 gRPC 转码语法。
路径参数
参数 | |
---|---|
scriptId |
要执行的脚本的 ID。在项目设置页面的“ID”下找到脚本 ID。 |
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "function": string, "parameters": [ value ], "sessionState": string, "devMode": boolean } |
字段 | |
---|---|
function |
要在给定脚本中执行的函数的名称。名称不包含括号或参数。它可以引用所包含的库(例如 |
parameters[] |
要传递给正在执行的函数的参数。每个参数的对象类型应与 Apps 脚本中的预期类型一致。参数不能是特定于 Apps 脚本的对象类型(例如 |
sessionState |
已弃用。仅适用于 Android 插件。表示用户在 Android 版 Google 文档或表格应用中的当前会话的 ID,作为额外数据包含在用于启动该插件的 Intent 中。当 Android 插件在会话状态下运行时,它会获得绑定脚本的权限,也就是说,该插件可以访问用户的当前光标位置(在文档中)或所选单元格(在表格中)等信息。如需检索状态,请调用 |
devMode |
如果 |
响应正文
如果成功,响应正文将包含结构如下的数据:
以 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 |
字段 | |
---|---|
done |
此字段指示脚本执行是否已完成。已完成的执行会有一个已填充的 |
联合字段 result 。操作结果,可以是 error ,也可以是有效的 response 。如果 done == false ,则既不会设置 error ,也不会设置 response 。如果 done == true ,则可以仅设置 error 或 response 中的一个。部分服务可能不会提供结果。result 只能是下列其中一项: |
|
error |
如果 |
response |
如果脚本函数成功返回,此字段会包含一个 此对象可以包含任意类型的字段。附加字段 |
授权范围
需要以下 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 |
状态代码。对于此 API,此值可以是以下任何一种:
|
message |
向开发者显示的错误消息(采用英语)。任何向用户显示的错误消息都会进行本地化并通过 |
details[] |
包含单个 此对象可以包含任意类型的字段。附加字段 |