API docs by Redocly

本体查询 · 本体查询 API (0.2.0)

Download OpenAPI specification:

Schema and data-query endpoints resolve trusted dependencies from the published main knowledge-network model and require the real caller's view_detail or query_data on every canonical {resource_type}:{kn_id}/{child_id} dependency before reading metadata or data. The service then resolves the knowledge network's active managed proxy; Vega performs the final corresponding resource permission check for that proxy through its restricted internal endpoint.

Action submission requires the caller's action_type.execute plus all input/target object dependencies' query_data. Tool Box or MCP execute belongs to the managed proxy and is checked again by the restricted execution endpoint. Proxy identity and target bindings are always server-derived from the current published main model. See ../knowledge-network-authorization.md and trusted-proxy-context.md. Instance and subgraph reads use ignore_local_index (default false) to bypass a resource's local index where supported. Applicability and operator support depend on the resource's query capabilities in Vega. This replaces the ineffective ignoring_store_cache parameter; no compatibility alias is provided. Object responses expose Vega's actual query_source (local_index or source) instead of search_from_index. Clients must migrate these names together with the server. The internal cursor digest encoding remains unchanged. Changing ignore_local_index requires a new query rather than continuing an existing cursor.

获取 Ontology Query 健康状态和平台版本

返回 Ontology Query 运行时信息。当前所有服务统一发布版本时，ServerVersion 表示平台版本。

Responses

Response samples

Content type
application/json
{
  • "ServerName": "string",
  • "ServerVersion": "string",
  • "Language": "string",
  • "GoVersion": "string",
  • "GoArch": "string"
}

Get the bound Vega schema in an object-type context

Requires the caller's object_type.view_detail. The target resource is resolved from the current published main model; Vega performs the final resource.view_detail check for the knowledge network's managed proxy. Proxy identities and resource IDs supplied by the client are ignored.

Authorizations:
OAuth2
path Parameters
kn_id
required
string
ot_id
required
string
query Parameters
branch
string
Default: "main"
Value: "main"

Responses

Response samples

Content type
application/json
{
  • "schema_definition": [
    ]
}

Get object-type sample data through the managed proxy

Requires the caller's object_type.query_data. The target resource is resolved from the current published main model and Vega performs the final managed-proxy resource.query_data check before reading rows.

Authorizations:
OAuth2
path Parameters
kn_id
required
string
ot_id
required
string
query Parameters
branch
string
Default: "main"
Value: "main"
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
need_total
boolean
Default: true
cursor
string

Opaque authenticated pagination cursor returned by the previous response. Raw search_after values are rejected.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "columns": [
    ],
  • "entries": [
    ],
  • "total_count": 0,
  • "cursor": "string",
  • "paging": {
    }
}

检索指定对象类的对象的详细数据

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

ot_id
required
string

对象类ID

query Parameters
branch
string
Default: "main"

分支，默认 main

include_type_info
boolean

是否包含对象类信息, 默认false，不包含

include_logic_params
boolean

包含逻辑属性的计算参数，默认false，返回结果不包含逻辑属性的字段和值

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display" "_score"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）、_score（相关性分数）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

ignore_local_index
boolean

是否跳过资源的本地索引并查询数据源，默认 false；参数是否适用及 match/knn 等算子是否受支持，由 Vega 根据资源的查询能力决定。

header Parameters
X-HTTP-Method-Override
required
string
Value: "GET"

重载 post，实际上是 get 方法

Request Body schema: application/json
required
One of
condition_and (object) or condition_or (object) or condition_eq (object) or condition_not_eq (object) or condition_gt (object) or condition_gte (object) or condition_lt (object) or condition_lte (object) or condition_in (object) or condition_not_in (object) or condition_like (object) or condition_not_like (object) or condition_range (object) or condition_out_range (object) or condition_exist (object) or condition_not_exist (object) or condition_regex (object) or condition_match (object) or condition_match_phrase (object) or condition_knn (object) or condition_multi_match (object) (Condition)
Array of objects (Sort)

排序字段，默认使用 _score 倒序，主键字段正序

limit
required
integer

返回的数量，默认值 10。范围 1-10000

need_total
boolean

是否需要总数，默认false

properties
Array of strings

指定需要输出的属性集。默认为全部数据属性

Responses

Request samples

Content type
application/json
Example
{
  • "condition": {
    },
  • "need_total": true,
  • "limit": 10
}

Response samples

Content type
application/json
Example
{
  • "object_type": {
    },
  • "datas": [
    ],
  • "total_count": 1,
  • "cursor": "opaque-authenticated-cursor"
}

行动查询

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络id

at_id
required
string

行动类id

query Parameters
branch
string
Default: "main"

分支名称，默认 main

include_type_info
boolean
Default: false

是否包含行动类信息（true/false）。未传时按 false 处理。

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

header Parameters
x-http-method-override
required
string
Value: "GET"

必须为 GET，与 POST 语义组合以实现「POST 载荷 + GET 语义」的行动查询。

Request Body schema: application/json
required
Array of objects (InstanceIdentity)

目标对象主键列表。每项为主键字段名到值的映射。可为空数组或省略，表示由服务端依据行动类绑定与条件拉取候选实例。

object

行动类「动态输入」参数取值（与行动类 parameters 中 value_from=input 的 name 对应，支持点分路径表示嵌套键）。 当行动类定义了此类参数且要求客户端提供时须传入对应非 null 取值，否则可能在业务层返回 400（例如 OntologyQuery.ActionType.InvalidParameter.DynamicParams）。

Responses

Request samples

Content type
application/json
{
  • "_instance_identities": [
    ],
  • "dynamic_params": {
    }
}

Response samples

Content type
application/json
{
  • "action_type": {
    },
  • "action_source": {
    },
  • "actions": [
    ],
  • "total_count": 1,
  • "overall_ms": 1163
}

子图查询

子图查询，可以是基于起点、方向和路径长度获取对象子图，有可以是基于路径获取对象子图，查询请求方式和返回体不同

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

query Parameters
branch
string

分支名称，默认 main（与实现 DefaultQuery branch 一致）

include_logic_params
boolean

包含逻辑属性的计算参数，默认false，返回结果不包含逻辑属性的字段和值

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

query_type
string
Enum: "" "relation_path"

查询类型，默认是子图探索，即基于起点、方向和路径长度获取对象子图；若是relation_path，则表示基于路径获取对象子图

ignore_local_index
boolean

是否跳过资源的本地索引并查询数据源，默认 false；参数是否适用及 match/knn 等算子是否受支持，由 Vega 根据资源的查询能力决定。

header Parameters
x-http-method-override
required
string
Value: "GET"

重载 POST，须为 GET（与对象实例查询等接口一致，实现中强制校验）

Request Body schema: application/json
required

子图查询请求体

One of
concept_groups
Array of strings

概念分组id数组

source_object_type_id
required
string

起点对象类id

condition_and (object) or condition_or (object) or condition_eq (object) or condition_not_eq (object) or condition_gt (object) or condition_gte (object) or condition_lt (object) or condition_lte (object) or condition_in (object) or condition_not_in (object) or condition_like (object) or condition_not_like (object) or condition_range (object) or condition_out_range (object) or condition_exist (object) or condition_not_exist (object) or condition_regex (object) or condition_match (object) or condition_match_phrase (object) or condition_knn (object) or condition_multi_match (object) (Condition)
direction
required
string
Enum: "forward" "backward" "bidirectional"

探索子图的路径方向

path_length
required
integer

探索子图的路径的最大长度

include_incomplete_path
boolean
Default: false

是否包含不完整的路径。默认是false，不包含，只返回完整的路径

Array of objects (Sort)

对起点类的排序字段

limit
integer

对起点类的对象数量的限制。默认是10

need_total
boolean

是否需要(起点类)总数，默认false。

cursor
string

上次查询返回的不透明且经过认证的起点对象分页游标；第一次查询不传此字段

Responses

Request samples

Content type
application/json
Example
{
  • "source_object_type_id": "comment",
  • "direction": "forward",
  • "path_length": 2,
  • "need_total": true,
  • "limit": 2
}

Response samples

Content type
application/json
Example
{
  • "objects": {
    },
  • "relation_paths": [
    ],
  • "total_count": 151043,
  • "cursor": "opaque-authenticated-cursor",
  • "current_path_number": 44,
  • "overall_ms": 4204
}

基于一组对象实例组织关系子图

给定一组对象实例，按概念定义的关系，组织这些对象实例的关系子图。

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

query Parameters
branch
string

分支名称

include_type_info
boolean

是否包含对象类信息，默认false，不包含

include_logic_params
boolean

包含逻辑属性的计算参数，默认false，返回结果不包含逻辑属性的字段和值

ignore_local_index
boolean

是否跳过资源的本地索引并查询数据源，默认 false；参数是否适用及 match/knn 等算子是否受支持，由 Vega 根据资源的查询能力决定。

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

Request Body schema: application/json
required

基于一组对象实例探索关系子图的请求体

required
Array of objects (InputObjectInstance)

对象实例数组

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "objects": {
    },
  • "isolated_objects": {
    },
  • "relation_paths": [
    ],
  • "overall_ms": 150
}

对象属性值查询

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

ot_id
required
string

对象类ID

query Parameters
branch
string

分支名称，默认 main

include_type_info
boolean

是否包含对象类信息，默认 false

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

header Parameters
x-http-method-override
required
string
Value: "GET"

重载 post，实际上是 get 方法

Request Body schema: application/json
required

属性查询请求体

required
Array of objects (InstanceIdentity)

对象主键的数组，代表多个对象。每项为 map，key 为主键属性名，value 为对应的属性值

properties
required
Array of strings

属性列表

object

各逻辑属性所需的动态参数：外层 key 为逻辑属性名，内层为参数名到取值的 map，取值可为任意 JSON。 参数名含 . 时按嵌套对象读取，例如参数 a.b 需传 {"a": {"b": <值>}}，扁平 key "a.b" 不会被识别。 未传或某属性无动态需求时可省略该 key；属性定义了 value_from=input 的参数却未传对应 key 时返回 400。

Responses

Request samples

Content type
application/json
{
  • "_instance_identities": [
    ],
  • "properties": [
    ],
  • "dynamic_params": {
    }
}

Response samples

Content type
application/json
{
  • "datas": [
    ],
  • "overall_ms": 2588
}

执行行动类

异步提交行动执行，立即返回 execution_id。执行主体只来自认证上下文， 请求体中的 dynamic_params 不能覆盖它。

认证开启时，提交和真实外调前都要求具体 Action Type 的 execute、 引用的 tool_box 或 MCP 的 execute，以及目标、affect 和 impact contract 引用对象类的 query_data。action_type.execute 不从父知识网络继承。 默认启用防重复：同一知识网络、行动类、目标实例与 dynamic_params 指纹在配置窗口内 若已有进行中（pending/running）且 start_time 落在窗口内的执行，则返回 409。

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

at_id
required
string

行动类ID

query Parameters
branch
string

分支名称，默认 main

Request Body schema: application/json
required
Array of objects (InstanceIdentity)

目标对象唯一标识列表；扫描模式下可传空数组，由服务端按行动条件拉取实例

object

与行动类 input 参数名对应的取值（支持点分路径）。有 input 参数时必填且不能为 null。

Responses

Request samples

Content type
application/json
{
  • "_instance_identities": [
    ],
  • "dynamic_params": {
    }
}

Response samples

Content type
application/json
{
  • "execution_id": "cqq2g8h4d2fg00fvm8dg",
  • "status": "pending",
  • "message": "Action execution started",
  • "created_at": 1704067200000
}

获取行动执行状态

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

execution_id
required
string

执行ID

Responses

Response samples

Content type
application/json
{
  • "id": "cqq2g8h4d2fg00fvm8dg",
  • "kn_id": "kn_xxx",
  • "action_type_id": "at_xxx",
  • "action_type_name": "restart_pod",
  • "action_source_type": "tool",
  • "object_type_id": "ot_xxx",
  • "trigger_type": "manual",
  • "status": "completed",
  • "total_count": 2,
  • "success_count": 1,
  • "failed_count": 1,
  • "results": [
    ],
  • "executor_id": "user_xxx",
  • "executor": {
    },
  • "start_time": 1704067200000,
  • "end_time": 1704067206200,
  • "duration_ms": 6200
}

查询行动执行日志

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

query Parameters
action_type_id
string

行动类ID（可选）

status
string
Enum: "pending" "running" "completed" "failed" "cancelled"

执行状态（可选）

trigger_type
string
Enum: "manual" "scheduled"

触发类型（可选）

keyword
string <= 128 characters

按执行 ID 过滤（可选）：不区分大小写的字面子串匹配，*、?、\ 按普通字符处理。 首尾空白会被去掉；最长 128 个字符，超长返回 400。同时作用于 total_count。

start_time_from
integer <int64>

开始时间范围-起始（毫秒时间戳，可选）

start_time_to
integer <int64>

开始时间范围-结束（毫秒时间戳，可选）

limit
integer
Default: 20

返回数量限制，默认20，最大1000

offset
integer
Default: 0

偏移量，默认 0；与 search_after 互斥，传了 search_after 后本参数失效

need_total
boolean
Default: false

是否需要返回总数

search_after
string

分页游标（逗号分隔字符串，如 "1704067200000,cqq2g8h4d2fg00fvm8dg"）

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 100,
  • "search_after": [
    ]
}

获取单条行动执行日志

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

log_id
required
string

日志ID (即执行ID)

query Parameters
results_limit
integer
Default: 100

results 分页大小，默认100，最大1000

results_offset
integer
Default: 0

results 偏移量，默认0；results_offset + results_limit 不得超过 10000

results_status
string
Enum: "success" "failed"

按 results 中的状态过滤（可选）

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kn_id": "string",
  • "action_type_id": "string",
  • "action_type_name": "string",
  • "action_source_type": "tool",
  • "object_type_id": "string",
  • "trigger_type": "manual",
  • "status": "pending",
  • "execution_mode": "once",
  • "target_count": 0,
  • "total_count": 0,
  • "success_count": 0,
  • "failed_count": 0,
  • "results": [
    ],
  • "results_total": 0,
  • "results_offset": 0,
  • "results_limit": 0,
  • "dynamic_params": { },
  • "executor_id": "string",
  • "executor": {
    },
  • "start_time": 0,
  • "end_time": 0,
  • "duration_ms": 0,
  • "instance_identity_hash": "string",
  • "action_type_snapshot": { },
  • "action_source": {
    }
}

分页查询单次执行的逐实例结果

返回单次执行的逐实例结果，分页与状态过滤在存储层完成，按实例在本次执行中的顺序排列。 执行摘要请用详情接口；本接口适合翻阅超过一页的结果。早期写入、结果内嵌在执行记录中的执行同样可查。

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

log_id
required
string

日志ID (即执行ID)

query Parameters
offset
integer >= 0
Default: 0

偏移量，默认 0；offset + limit 不得超过 10000

limit
integer
Default: 100

分页大小，默认 100，最大 1000（超出按 1000 处理）

status
string
Enum: "success" "failed" "cancelled"

按结果状态过滤（可选）

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 3
}

取消正在执行的任务

Authorizations:
OAuth2
path Parameters
kn_id
required
string

业务知识网络ID

log_id
required
string

日志ID (即执行ID)

Request Body schema: application/json
optional
reason
string

取消原因（可选）

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "execution_id": "cqq2g8h4d2fg00fvm8dg",
  • "status": "cancelled",
  • "message": "任务已取消",
  • "cancelled_count": 5,
  • "completed_count": 10
}