兼容接口

以下 4 项操作供既有接入使用，全部保留可调用入口。只有 health 在当前 Controller 显式标记 Deprecated；clock 与 visualization 系列在本教程归入兼容流程，不将分组标签误当作代码弃用注解。

兼容约定

health 验证服务与凭证，不能判断仿真实例是否完成。按名称查询单个对象已作为正式对象接口，见“对象与统计”。

clock 的时间单位为仿真微秒。visualization/snapshot 返回 resources、nodes、simulationTimeMicros 与 cursor；updates/poll 使用该 cursor 读取 updates 并采用 nextCursor。旧格式与新 animation 的 assets、motions、batches 分开处理。

先取得兼容快照，再增量读取；遇到 generation 变化或 cursor 过期重新获取兼容快照。不能把新 animation 游标传给旧 visualization，也不能凭空增加 sequence。现有旧动画格式保持原样。

接口参考与调用示例

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

服务与凭证检查

GET /simulation/openapi/v1/health

仅供既有接入验证服务和凭证，不代表任一实例完成。

在测试页打开 →

请求参数

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

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

请求示例

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

GET /simulation/openapi/v1/health
X-Foresim-Api-Key: <api-key>
Accept: application/json

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "status": "example",
    "serverTime": "2026-01-01T00:00:00Z"
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`status`	string	是	见字段结构
`serverTime`	string (date-time)	是	见字段结构

典型失败与下一步

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}/clock

实例属于当前凭证且 runtimeAvailable=true；对象与表标识只能在所属实例内使用。

在测试页打开 →

请求参数

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

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

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

请求示例

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

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

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "simulationId": "example_simulationId",
    "simulationTimeMicros": 0,
    "status": "READY",
    "runMode": "REAL_TIME",
    "speedMultiplier": null,
    "runtimeAvailable": true,
    "flowControl": "example",
    "statusReasonCode": null,
    "sampledAt": "2026-01-01T00:00:00Z"
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`simulationId`	string	是	本次创建返回的实例编号
`simulationTimeMicros`	integer (int64)	是	见字段结构
`status`	string READY / RUNNING / PAUSED / COMPLETED / STOPPED / FAILED	是	见字段结构
`runMode`	string / null REAL_TIME / EVENT_DRIVEN / FULL_SPEED /	是	FULL_SPEED 不传倍速；有限结束时刻必须大于当前仿真时间
`speedMultiplier`	integer (int32) / null	是	省略/null 默认 1，仅 REAL_TIME / EVENT_DRIVEN 使用
`runtimeAvailable`	boolean	是	见字段结构
`flowControl`	string	是	见字段结构
`statusReasonCode`	string / null	是	见字段结构
`sampledAt`	string (date-time)	是	见字段结构

典型失败与下一步

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

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

兼容可视化快照

GET /simulation/openapi/v1/simulations/{simulationId}/visualization/snapshot

兼容可视化协议；运行资源可用，和新动画协议分别保存状态。

在测试页打开 →

请求参数

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

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

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

请求示例

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

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

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "simulationId": "example_simulationId",
    "cursor": {
      "generation": "example_generation",
      "sequence": 0
    },
    "simulationTimeMicros": 0,
    "resources": [],
    "nodes": []
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`simulationId`	string	是	本次创建返回的实例编号
`cursor`	object	是	使用对应协议的快照 cursor 或增量 nextCursor；错误时不推进
`simulationTimeMicros`	integer (int64)	是	见字段结构
`resources`	array	是	见字段结构
`nodes`	array	是	见字段结构

典型失败与下一步

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

错误示例仅说明报文结构，具体错误码见错误处理。下一步：兼容可视化增量。

兼容可视化增量

POST /simulation/openapi/v1/simulations/{simulationId}/visualization/updates/poll

先获取兼容可视化快照；使用其完整 cursor，不能传入新动画游标。

在测试页打开 →

请求参数

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

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

字段	类型与约束	必填	说明
`cursor`	object	是	使用对应协议的快照 cursor 或增量 nextCursor；错误时不推进
`limit`	integer (int32) / null minimum=1，maximum=500	否	省略/null 默认 100；上限见 capabilities.limits.maximumUpdatesPerPoll

请求示例

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

POST /simulation/openapi/v1/simulations/{simulationId}/visualization/updates/poll
X-Foresim-Api-Key: <api-key>
Accept: application/json
Content-Type: application/json

{
  "cursor": {{visualizationCursor}},
  "limit": 100
}

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "simulationId": "example_simulationId",
    "nextCursor": {
      "generation": "example_generation",
      "sequence": 0
    },
    "oldestAvailableSequence": 0,
    "latestSequence": 0,
    "hasMore": false,
    "flowControl": "example",
    "updates": []
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`simulationId`	string	是	本次创建返回的实例编号
`nextCursor`	object	是	见字段结构
`oldestAvailableSequence`	integer (int64)	是	见字段结构
`latestSequence`	integer (int64)	是	见字段结构
`hasMore`	boolean	是	见字段结构
`flowControl`	string	是	见字段结构
`updates`	array	是	见字段结构

典型失败与下一步

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

错误示例仅说明报文结构，具体错误码见错误处理。下一步：兼容可视化增量。

兼容约定​

接口参考与调用示例​

服务与凭证检查​

请求参数

请求示例

成功响应结构

典型失败与下一步

查询仿真时钟​

请求参数

请求示例

成功响应结构

典型失败与下一步

兼容可视化快照​

请求参数

请求示例

成功响应结构

典型失败与下一步

兼容可视化增量​

请求参数

请求示例

成功响应结构

典型失败与下一步

兼容约定

接口参考与调用示例

服务与凭证检查

查询仿真时钟

兼容可视化快照

兼容可视化增量