脚本提交与执行结果

脚本在指定实例内运行，可读取或修改运行对象。当前契约是 POST 提交 + GET 查询：首次提交返回 HTTP 202 和 executionId，重放返回 HTTP 200 与当前执行快照。不能将 HTTP 200/202 等同脚本成功。

提交方式

INLINE 的 source 必须恰好含 type=INLINE 和 code；NAMED 必须恰好含 type=NAMED 和 scriptName。两种方式互斥。NAMED 使用当前场景确实存在的 Groovy Script 精确名称，不自动创建脚本。

entityName 可选。INLINE 省略时没有执行对象；NAMED 省略时采用 Script 已配置的 owner。parameters 省略或 null 等同空对象，在脚本中通过 params 读取。代码最长 65536 字符，参数与结果各最多 65536 UTF-8 字节；实例配额以 capabilities.scripts 为准。

? 表示执行对象，@ 表示该对象的 Cont。缺少对象或载荷时须判空；不要以内部绑定名替代占位符。测试页的最小 INLINE 示例仅返回 params.message。

状态与结果

status	解释	下一步
QUEUED	已受理	使用相同 executionId 查询
RUNNING	仍在执行或等待仿真事件	有限轮询，检查仿真暂停或动画背压
SUCCEEDED	实际执行成功	读取 result，null 也是有效值
FAILED	编译、执行或结果转换失败	查看 error.code / error.message，保留请求与实例标识
CANCELLED	执行被服务端取消	检查资源释放与实例状态

GET 返回 code=OK 只表示成功读取执行记录。若 data.status=FAILED，应按 data.error 处理。SCRIPT_COMPILATION_FAILED、SCRIPT_EXECUTION_FAILED、SCRIPT_RESULT_UNAVAILABLE 可出现在执行记录中；先前副作用不会自动回滚。资源释放后历史不能再读取。

幂等与等待

提交必须提供 8～128 个可打印 ASCII 字符的 Idempotency-Key。同实例、同键、同 source/entityName/parameters 重放已有执行；同键不同参数返回 IDEMPOTENCY_KEY_REUSED。执行未结束时换新键可能返回 SCRIPT_EXECUTION_IN_PROGRESS。

当前请求没有 waitForResult 字段；跟踪结果应调用下方 GET。浏览器取消或网络超时不能取消服务端脚本。等待仿真时间的脚本可能受暂停与背压影响。

接口参考与调用示例

以下为结构示例，未代表当前环境实测。路径中的标识和请求变量使用本次响应或获授权的配置。

提交脚本执行

POST /simulation/openapi/v1/simulations/{simulationId}/script-executions

runtimeAvailable=true，状态为 READY、RUNNING、PAUSED 或 COMPLETED；脚本可修改当前实例，不能假定自动回滚。

在测试页打开 →

请求参数

认证头 X-Foresim-Api-Key 由调用方服务端添加；可选 X-Request-Id 用于关联请求。当前接口没有查询字符串参数。

位置	字段	类型	必填与说明
path	`simulationId`	string	必填。本次创建返回的实例编号
header	`Idempotency-Key`	string	必填。8～128 个可打印 ASCII 字符；重试同一操作必须复用原键和原参数

字段	类型与约束	必填	说明
`source`	互斥结构	是	恰好选择 INLINE(type + code) 或 NAMED(type + scriptName)
`entityName`	string / null minLength=0，maxLength=256	否	精确对象名；脚本或场景表查询中可省略，含义见对应章节
`parameters`	object / null	否	脚本 params；省略/null 等同 {}，最多 65536 UTF-8 字节

请求示例

双花括号是测试页变量，发送时替换；下列模板尚未发送。

POST /simulation/openapi/v1/simulations/{simulationId}/script-executions
X-Foresim-Api-Key: <api-key>
Accept: application/json
Idempotency-Key: <new-operation-key>
Content-Type: application/json

{
  "source": {
    "type": "INLINE",
    "code": "return params.message"
  },
  "parameters": {
    "message": "Hello ForeSim"
  }
}

成功响应结构

首次成功 HTTP 202；相同幂等请求重放为 HTTP 200，并返回 Idempotent-Replayed: true。外层 code=OK。下方是结构示例，值与空数组不代表实测数据。

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "executionId": "example_executionId",
    "status": "QUEUED",
    "sourceType": "INLINE",
    "scriptName": null,
    "entityName": null,
    "submittedAt": "2026-01-01T00:00:00Z",
    "startedAt": null,
    "completedAt": null,
    "result": null,
    "error": null
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`executionId`	string	是	本实例脚本提交返回的编号
`status`	string QUEUED / RUNNING / SUCCEEDED / FAILED / CANCELLED	是	见字段结构
`sourceType`	string INLINE / NAMED	是	见字段结构
`scriptName`	string / null	是	见字段结构
`entityName`	string / null	是	精确对象名；脚本或场景表查询中可省略，含义见对应章节
`submittedAt`	string (date-time)	是	见字段结构
`startedAt`	string (date-time) / null	是	见字段结构
`completedAt`	string (date-time) / null	是	见字段结构
`result`	互斥结构 / null	是	见字段结构
`error`	object / null	是	见字段结构

典型失败与下一步

401 检查服务端凭证；403 检查来源和实例归属；400 检查 details 中的字段；409 检查状态、幂等键或名称歧义；410 表示资源已释放；429 按 Retry-After 停止并等待。保留实际 requestId。

{"code":"INVALID_REQUEST","message":"Invalid request","requestId":"example_error","details":[{"field":"request","reason":"检查必填字段和前置状态"}]}

错误示例仅说明报文结构，具体错误码见错误处理。下一步：查询脚本执行结果。

查询脚本执行结果

GET /simulation/openapi/v1/simulations/{simulationId}/script-executions/{executionId}

使用本实例提交返回的 executionId；运行资源尚未释放。

在测试页打开 →

请求参数

认证头 X-Foresim-Api-Key 由调用方服务端添加；可选 X-Request-Id 用于关联请求。当前接口没有查询字符串参数。

位置	字段	类型	必填与说明
path	`simulationId`	string	必填。本次创建返回的实例编号
path	`executionId`	string	必填。本实例脚本提交返回的编号

无请求体，不发送空 JSON 代替省略。

请求示例

双花括号是测试页变量，发送时替换；下列模板尚未发送。

GET /simulation/openapi/v1/simulations/{simulationId}/script-executions/{executionId}
X-Foresim-Api-Key: <api-key>
Accept: application/json

成功响应结构

首次成功 HTTP 200；外层 code=OK。下方是结构示例，值与空数组不代表实测数据。

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "executionId": "example_executionId",
    "status": "QUEUED",
    "sourceType": "INLINE",
    "scriptName": null,
    "entityName": null,
    "submittedAt": "2026-01-01T00:00:00Z",
    "startedAt": null,
    "completedAt": null,
    "result": null,
    "error": null
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`executionId`	string	是	本实例脚本提交返回的编号
`status`	string QUEUED / RUNNING / SUCCEEDED / FAILED / CANCELLED	是	见字段结构
`sourceType`	string INLINE / NAMED	是	见字段结构
`scriptName`	string / null	是	见字段结构
`entityName`	string / null	是	精确对象名；脚本或场景表查询中可省略，含义见对应章节
`submittedAt`	string (date-time)	是	见字段结构
`startedAt`	string (date-time) / null	是	见字段结构
`completedAt`	string (date-time) / null	是	见字段结构
`result`	互斥结构 / null	是	见字段结构
`error`	object / null	是	见字段结构

典型失败与下一步

{"code":"INVALID_REQUEST","message":"Invalid request","requestId":"example_error","details":[{"field":"request","reason":"检查必填字段和前置状态"}]}

错误示例仅说明报文结构，具体错误码见错误处理。下一步：查询实例状态。

提交方式​

状态与结果​

幂等与等待​

接口参考与调用示例​

提交脚本执行​

请求参数

请求示例

成功响应结构

典型失败与下一步

查询脚本执行结果​

请求参数

请求示例

成功响应结构

典型失败与下一步

提交方式

状态与结果

幂等与等待

接口参考与调用示例

提交脚本执行

查询脚本执行结果