跳到主要内容

结果表

6 结果表接口​

结果表查询统一使用表名称；对象所属表可再用 entityName 限定，不需要对象内部编号。

6.1 表格结构​

表描述包含 tableId、name、scope、ownerEntityName 和 columns。scope=SCENE 表示场景表，此时 ownerEntityName=null；scope=ENTITY 表示对象拥有的表，ownerEntityName 是所属对象的完整名称。tableId 仅作为响应中的稳定标识和审计信息，不作为查询参数。

列定义包含 name、dataType 和 nullable。dataType 可取 STRING、INTEGER、DECIMAL、BOOLEAN、DATE、DATETIME、JSON 或 NULL。rows 中每个对象以列名为键，值保留对应 JSON 类型。

6.2 查询结果表目录​

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

请求字段类型与必填含义
ownerEntityNames字符串数组，可选，最多 200按所属对象完整名称筛选
nameContains字符串，可选，最长 128表名包含匹配
page、pageSize正整数，可选页码与页大小

ownerEntityNames 省略、为 null 或为空时不限制归属。返回 items、page 和 observation；没有匹配时 items=[]。

6.3 读取结果表记录​

POST /simulations/{simulationId}/tables/query

请求字段类型与必填含义
tableName非空字符串，必填，最长 256完整表名；指定所属对象后也可使用该对象的局部表名
entityName字符串，可选，最长 256所属对象的完整名称，用于消除同名表歧义
page、pageSize正整数，可选页码从 1 开始，默认每页 100 条，最大 500 条

名称精确匹配且区分大小写。未找到对象或表格分别返回 HTTP 404 ENTITY_NOT_FOUND、TABLE_NOT_FOUND；多个表格符合条件时返回 HTTP 409 TABLE_NAME_AMBIGUOUS。响应包含表描述、rows、分页信息和读取时刻；运行资源已释放时返回 HTTP 410 SIMULATION_RUNTIME_RELEASED。

接口参考与调用示例​

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

查询结果表目录​

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

实例属于当前凭证且 runtimeAvailable=true；可按所属对象名称筛选。

在测试页打开 →

请求参数

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

位置字段类型必填与说明
pathsimulationIdstring必填。本次创建返回的实例编号
字段类型与约束必填说明
ownerEntityNamesarray / null
minItems=0，maxItems=200
否按对象名称过滤表归属，省略/null/空数组时不限制
nameContainsstring / null
minLength=0，maxLength=128
否名称包含匹配；省略/null/空字符串时不限制
pageinteger (int32) / null
minimum=1
否从 1 开始；省略/null 默认 1
pageSizeinteger (int32) / null
minimum=1
否省略/null 默认 100；上限见 capabilities.limits.maximumPageSize

请求示例

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

POST /simulation/openapi/v1/simulations/{simulationId}/tables/catalog/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
    }
  }
}
展开完整响应字段定义
字段类型与约束必填说明
itemsarray是见字段结构
pageobject是从 1 开始；省略/null 默认 1
observationobject是见字段结构

典型失败与下一步

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

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

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

读取结果表记录​

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

实例属于当前凭证且 runtimeAvailable=true；表名精确匹配，重名时填写 entityName 限定所属对象。

在测试页打开 →

请求参数

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

位置字段类型必填与说明
pathsimulationIdstring必填。本次创建返回的实例编号
字段类型与约束必填说明
tableNamestring
minLength=1，maxLength=256
是精确表名；歧义时补充 entityName
entityNamestring / null
minLength=0，maxLength=256
否精确对象名；脚本或场景表查询中可省略，含义见对应章节
pageinteger (int32) / null
minimum=1
否从 1 开始；省略/null 默认 1
pageSizeinteger (int32) / null
minimum=1
否省略/null 默认 100；上限见 capabilities.limits.maximumPageSize

请求示例

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

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

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

成功响应结构

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

{
  "code": "OK",
  "message": "Success",
  "requestId": "example_request",
  "data": {
    "tableId": "example_tableId",
    "name": "example",
    "scope": "SCENE",
    "ownerEntityName": null,
    "columns": [],
    "rows": [],
    "page": {
      "number": 0,
      "size": 0,
      "totalElements": 0,
      "totalPages": 0
    },
    "observation": {
      "simulationTimeStartMicros": 0,
      "simulationTimeEndMicros": 0,
      "timeStable": false,
      "consistent": false
    }
  }
}
展开完整响应字段定义
字段类型与约束必填说明
tableIdstring是见字段结构
namestring是见字段结构
scopestring
SCENE / ENTITY
是见字段结构
ownerEntityNamestring / null是见字段结构
columnsarray是见字段结构
rowsarray是见字段结构
pageobject是从 1 开始；省略/null 默认 1
observationobject是见字段结构

典型失败与下一步

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

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

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