对象与统计

5 对象与统计接口

对象和统计接口统一使用当前实例中的 entityName。客户端不需要获取或保存对象内部编号；名称精确匹配时区分大小写，并保留首尾空白。

5.1 查询对象

POST /simulations/{simulationId}/entities/query

请求字段	类型与必填	含义与限制
`entityNames`	字符串数组，可选，最多 200	按一个或多个完整对象名称精确筛选
`categories`	枚举数组，可选，最多 100	按业务分类筛选
`nameContains`	字符串，可选，最长 128	不区分大小写的名称包含匹配
`page`、`pageSize`	正整数，可选	页码从 1 开始；默认页大小和上限见 capabilities

多个条件同时生效。可选数组省略、为 null 或为空时不按该字段过滤。响应 items 中每项包含 entityName、category、capabilities、operatingState 和 observation；没有匹配对象时返回空数组。

5.2 按名称查询单个对象

GET /simulations/{simulationId}/entities/{entityName}

entityName 是当前实例中的完整对象名称，需要进行 URL 编码。不存在时返回 HTTP 404 ENTITY_NOT_FOUND；同名导致无法唯一确定时返回 HTTP 409 ENTITY_NAME_AMBIGUOUS。

5.3 查询统计属性目录

POST /simulations/{simulationId}/statistics/catalog/query

请求体可传 entityNames，最多 200 项；省略、null 或空数组表示查询当前实例中的全部对象。响应结构如下：

响应字段	含义
`definitions[]`	统计属性定义，包含 `modelCode`、`propertyName`、`description` 和 `dataType`
`entities[]`	对象目录，包含 `entityName`、`modelCode`、`status` 和 `propertyNames`

默认统计属性来自 Studio 的模型定义接口。服务至多每天刷新一次；只有响应状态、结构和统计属性定义全部有效时才替换缓存。远端超时、报错或返回异常数据时继续使用上一次成功缓存；首次启动还内置一份最后已知有效快照，因此查询链不会因 Studio 临时不可用而清空默认属性。

同名属性在不同 modelCode 下可能具有不同类型或含义，客户端应使用 modelCode + propertyName 关联定义。

5.4 查询统计结果

POST /simulations/{simulationId}/statistics/query

请求字段	类型与必填	含义与限制
`entityNames`	非空字符串数组，必填，最多 200	当前实例中的完整对象名称
`propertyNames`	字符串数组，可选，最多 50	指定需要读取的统计属性；省略、`null` 或空数组时，分别读取每个对象模型类型定义的全部默认统计属性

响应 entities[] 按对象返回 entityName、modelCode、对象级 status 以及 properties[]。每项属性包含 propertyName、status 和保留原 JSON 类型的 value。definitions[] 给出本次涉及的模型与属性定义，observation 给出本次读取的仿真时间范围。

状态	含义
`AVAILABLE`	属性存在，`value` 是实际读取值；值可以为 0、对象、数组或其他合法 JSON 类型
`NO_DATA`	属性已定义，但当前没有可返回的数据
`ENTITY_NOT_FOUND`	当前实例中没有该完整对象名称
`PROPERTY_NOT_FOUND`	已显式请求的属性不属于该对象的模型统计定义

不要把 NO_DATA 或 PROPERTY_NOT_FOUND 改写为数值 0。运行完成后只要 runtimeAvailable=true 仍可读取；运行资源释放后返回 HTTP 410。

接口参考与调用示例

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

查询对象

POST /simulation/openapi/v1/simulations/{simulationId}/entities/query

实例属于当前凭证且 runtimeAvailable=true；对象名称按当前实例精确匹配。

在测试页打开 →

请求参数

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

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

字段	类型与约束	必填	说明
`entityNames`	array / null minItems=0，maxItems=200	否	对象完整名称；精确匹配、区分大小写，不自动去除空白
`categories`	array / null minItems=0，maxItems=100	否	按稳定类别过滤，省略/null/空数组时不限制
`nameContains`	string / null minLength=0，maxLength=128	否	名称包含匹配；省略/null/空字符串时不限制
`page`	integer (int32) / null minimum=1	否	从 1 开始；省略/null 默认 1
`pageSize`	integer (int32) / null minimum=1	否	省略/null 默认 100；上限见 capabilities.limits.maximumPageSize

请求示例

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

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

{
  "page": 1,
  "pageSize": 100
}

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "items": [],
    "page": {
      "number": 0,
      "size": 0,
      "totalElements": 0,
      "totalPages": 0
    },
    "observation": {
      "simulationTimeStartMicros": 0,
      "simulationTimeEndMicros": 0,
      "timeStable": false,
      "consistent": false
    }
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`items`	array	是	见字段结构
`page`	object	是	从 1 开始；省略/null 默认 1
`observation`	object	是	见字段结构

典型失败与下一步

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}/entities/{entityName}

实例属于当前凭证且 runtimeAvailable=true；entityName 使用当前实例中的完整对象名称。

在测试页打开 →

请求参数

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

位置	字段	类型	必填与说明
path	`simulationId`	string	必填。本次创建返回的实例编号
path	`entityName`	string	必填。精确对象名；脚本或场景表查询中可省略，含义见对应章节

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

请求示例

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

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

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "entityName": "example",
    "category": "SOURCE",
    "capabilities": [],
    "operatingState": "example",
    "observation": {
      "simulationTimeStartMicros": 0,
      "simulationTimeEndMicros": 0,
      "timeStable": false,
      "consistent": false
    }
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`entityName`	string	是	精确对象名；脚本或场景表查询中可省略，含义见对应章节
`category`	string SOURCE / SINK / PROCESSOR / BUFFER / CONVEYOR / VEHICLE / CARGO / WORKER / STORAGE / TRANSPORT_DEVICE / ROUTE / TABLE / LOGIC / OTHER	是	见字段结构
`capabilities`	array	是	见字段结构
`operatingState`	string	是	见字段结构
`observation`	object	是	见字段结构

典型失败与下一步

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

错误示例仅说明报文结构，具体错误码见错误处理。下一步：查询统计属性目录。

查询统计属性目录

POST /simulation/openapi/v1/simulations/{simulationId}/statistics/catalog/query

实例属于当前凭证且 runtimeAvailable=true；可按对象名称筛选。目录来自 Studio 模型定义的每日缓存。

在测试页打开 →

请求参数

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

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

字段	类型与约束	必填	说明
`entityNames`	array / null minItems=0，maxItems=200	否	对象完整名称；精确匹配、区分大小写，不自动去除空白

请求示例

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

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

{
  "entityNames": [
    "{{entityName}}"
  ]
}

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "definitions": [],
    "entities": []
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`definitions`	array	是	见字段结构
`entities`	array	是	见字段结构

典型失败与下一步

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

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

查询统计结果

POST /simulation/openapi/v1/simulations/{simulationId}/statistics/query

实例属于当前凭证且 runtimeAvailable=true；entityNames 精确匹配，propertyNames 可省略以读取各模型默认统计属性。

在测试页打开 →

请求参数

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

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

字段	类型与约束	必填	说明
`entityNames`	array minItems=1，maxItems=200	是	对象完整名称；精确匹配、区分大小写，不自动去除空白
`propertyNames`	array / null minItems=0，maxItems=50	否	统计属性名；省略/null/空数组时使用各对象模型类型定义的默认统计属性

请求示例

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

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

{
  "entityNames": [
    "{{entityName}}"
  ]
}

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "definitions": [],
    "entities": [],
    "observation": {
      "simulationTimeStartMicros": 0,
      "simulationTimeEndMicros": 0,
      "timeStable": false,
      "consistent": false
    }
  }
}

展开完整响应字段定义

字段	类型与约束	必填	说明
`definitions`	array	是	见字段结构
`entities`	array	是	见字段结构
`observation`	object	是	见字段结构

典型失败与下一步

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

错误示例仅说明报文结构，具体错误码见错误处理。下一步：查询结果表目录。

5 对象与统计接口​

5.1 查询对象​

5.2 按名称查询单个对象​

5.3 查询统计属性目录​

5.4 查询统计结果​

接口参考与调用示例​

查询对象​

请求参数

请求示例

成功响应结构

典型失败与下一步

按名称查询单个对象​

请求参数

请求示例

成功响应结构

典型失败与下一步

查询统计属性目录​

请求参数

请求示例

成功响应结构

典型失败与下一步

查询统计结果​

请求参数

请求示例

成功响应结构

典型失败与下一步

5 对象与统计接口

5.1 查询对象

5.2 按名称查询单个对象

5.3 查询统计属性目录

5.4 查询统计结果

接口参考与调用示例

查询对象

按名称查询单个对象

查询统计属性目录

查询统计结果