运行一次计算
准备已启用的 OpenAPI 服务、由该服务颁发的 API Key，以及可运行、不读写外部设备的测试场景。场景应有限结束，并包含你需要的统计对象或结果表。
填写服务地址与密钥
打开 测试页，顶部“服务地址”默认为 https://api.engine.foresim.top/api/simulation。在下方“API Key”中粘贴当前服务颁发的密钥，再点击“检查连接”。页面自动添加 /openapi/v1/... 路径，并通过 X-Foresim-Api-Key 请求头认证。
密钥默认隐藏，可点击“显示密钥”检查；仅在当前页面内存中使用，刷新或重置会话后清除。切换服务地址后需重新填写该服务的 Key；本地测试服务颁发的 Key 不等同于生产服务的 Key。
成功响应应为 HTTP 2xx、code=OK。根据 capabilities 的 limits 设置分页、动画条数及结果保留时间。尚未填写 Key 时仍可查看示例。
创建并运行
- 选择 创建实例，把 sceneId 变量填为获授权的场景字符串，发送请求。页面采用真实返回的 simulationId。
- 选择 启动仿真，计算场景使用 FULL_SPEED、endTimeMicros=600000000（600 秒）。请按场景实际需求调整有限结束时刻，不传 speedMultiplier。
- 选择 查询状态，单次查看或主动开启有限轮询。COMPLETED 且 runtimeAvailable=true 时读取最终结果；FAILED 时先保存错误与 requestId。
- 发现对象，从真实响应列表选择目标名称；需要了解属性时读取统计属性目录。直接查询统计时可省略
propertyNames，由服务读取该对象模型类型定义的默认统计属性。 - 查询统计 或 发现结果表 并选择表、读取记录。检查数据状态、单位、页码与 observation，保存完整响应。
- 最后 释放本次实例，确认 runtimeAvailable=false。不要释放其他调用者的实例。
交互与脚本
暂停、继续和调速需要仍有操作窗口的交互实例。使用 REAL_TIME 或 EVENT_DRIVEN 时，同时按新动画快照和增量持续消费数据；只轮询状态无法消除动画背压。
脚本先 提交，再用本次 executionId 查询结果。QUEUED / RUNNING 都不是执行完成；只有 SUCCEEDED 表示成功，result=null 也可为有效结果。
结果不明确时
超时后保留请求快照、simulationId 和幂等键。用“重试原请求”复用同一参数和键；修改参数或点击“发送新请求”才代表新业务操作。脚本有副作用，不能因返回值未取得而自动重做。
3 实例生命周期与运行模式
3.1 实例状态与数据保留
| 状态 | 含义 | 结果读取 |
|---|---|---|
READY | 场景已加载，等待启动 | 可发现对象和数据目录 |
RUNNING | 仿真运行中 | 可读取当前数据 |
PAUSED | 已接受人工暂停 | 可读取暂停时的数据 |
COMPLETED | 仿真正常完成 | 保留期内可读取结果 |
FAILED | 仿真运行发生不可恢复的故障 | 运行资源尚在时可读取已形成的部分结果 |
STOPPED | 未正常完成的实例已被停止 | 运行资源已释放 |
COMPLETED、FAILED 和 STOPPED 是终态。runtimeAvailable 表示运行数据资源是否仍保留，具体查询仍可能返回相应读取错误。结果保留时长由能力接口返回；调用 stop 会提前释放。释放后仍可查询实例摘要，运行数据接口返回 HTTP 410 和 SIMULATION_RUNTIME_RELEASED。
3.2 运行模式与倍速
| 模式 | 适用业务 | 倍速与结束时间 |
|---|---|---|
FULL_SPEED | 快速取得最终统计结果 | 不传倍速；有限正结束时刻且大于当前仿真时间 |
REAL_TIME | 按指定节奏运行 | 倍速整数 1～100，省略为 1；结束时刻可为 -1 表示不限时 |
EVENT_DRIVEN | 按事件顺序推进仿真 | 同样有 1～100 倍速，省略为 1；结束时刻可为 -1 |
启动时省略 endTimeMicros 继承场景设置；调整运行设置时省略则继承实例已有设置。FULL_SPEED 仅在继承值满足有限结束条件时接受省略。任何模式的有限结束时刻都必须大于当前仿真时间；0 或小于 -1 的值不合法。
仅获取计算结果时使用 FULL_SPEED。REAL_TIME 和 EVENT_DRIVEN 会生成动画数据，应按第 7 章先获取快照，再持续读取增量；数据积压时仿真可能等待。仅轮询实例状态无法解除该等待。