统一目录拓扑查询¶
POST /api/v1/unified_catalog/topology/query
概述¶
查询统一目录拓扑关系。
Body 请求参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| entityType | string | 实体类型编码；filters 或 orderBy 涉及健康字段时必填 允许为空: False |
|
| urn | string | 聚焦实体 URN 允许为空: False |
|
| providers | array | 来源类型列表 允许为空: False |
|
| relationTypes | array | 关系类型列表，当前主要使用 links 和 contains 允许为空: False |
|
| orderBy | string | 起点实体排序字段；使用健康字段时必须传 entityType 允许为空: False |
|
| filters | json | 实体过滤字段，支持 attributes 中任意字段 允许为空: False |
|
| groupByFields | array | 按数组顺序进行多层级分组；entityType 读取实体顶层字段，其他字段读取 attributes 允许为空: False |
|
| search | string | 搜索关键词 允许为空: False |
参数补充说明¶
请求参数说明
| 参数名 | type | 必选 | 说明 |
|---|---|---|---|
| entityType | string | 健康查询时必选 | 起点实体类型编码；filters/orderBy 涉及健康字段时必须唯一指定 |
| urn | string | 否 | 聚焦实体 URN |
| providers | array[string] | 否 | 起点实体来源类型列表 |
| relationTypes | array[string] | 否 | 需要返回的关系类型列表 |
| orderBy | string | 否 | 起点实体排序字段；使用健康字段时必须传 entityType |
| filters | json | 否 | 起点实体过滤条件，支持 attributes 任意字段及顶层健康字段 |
| groupByFields | array[string] | 否 | 拓扑实体节点分组字段列表 |
| search | string | 否 | 起点实体搜索关键词 |
groupByFields 使用说明
- 按数组顺序做多层级分组，例如：
["project","env","serviceType"]。 entityType从实体顶层字段读取，其他字段从实体attributes读取。- 分组基于拓扑结果中的实体节点，而不是关系边。
groupInfo.groupByLayers[].groupByData.*.data[]和groupInfo.noGroupData[]返回healthScore/healthStatus；healthScore保留真实的0和null。
调用注意事项
entityType、providers、search、urn、filters只作用于起点实体确定。filters涉及healthStatus/healthScore/healthUpdateAt/brokenComponents及 snake_case 别名，或orderBy使用健康字段时，必须传entityType；Studio 按有效关闭态过滤、排序，不直接信任 kodo 中待异步清理的历史健康值。- 返回结构固定为
items + groupInfo。 - 平台内拓扑查询结果中，关系两端实体摘要的
attributes为全量返回。 - 关系两端和分组实体固定返回健康度开关与结果；所有类型始终按实体与类型有效配置计算，不依赖后台 readiness 清理进度。
请求例子¶
curl 'https://openapi.guance.com/api/v1/unified_catalog/topology/query' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"entityType":"service","filters":{"project":["demo"]},"groupByFields":["project"]}'
响应¶
{
"code": 200,
"content": {
"items": [
{
"relationType": "links",
"sourceUrn": "urn:system:default:core",
"targetUrn": "urn:service:default:demo",
"sourceUrnInfo": {
"urn": "urn:system:default:core",
"attributes": {
"project": "demo"
},
"healthConfig": {
"mode": "inherit"
},
"healthEnabled": true,
"healthScore": 67,
"healthStatus": "warning",
"healthUpdateAt": "2026-08-11 22:40:00"
},
"targetUrnInfo": {
"urn": "urn:service:default:demo",
"attributes": {
"project": "demo",
"env": "prod"
},
"healthConfig": {},
"healthEnabled": false,
"healthScore": null,
"healthStatus": "unknown",
"healthUpdateAt": null
}
}
],
"groupInfo": {
"groupByLayers": [
{
"groupByField": "project",
"groupByData": {
"demo": {
"data": [
{
"urn": "urn:system:default:core",
"entityType": "system",
"healthScore": 67,
"healthStatus": "warning",
"healthConfig": {
"mode": "inherit"
},
"healthEnabled": true,
"attributes": {
"project": "demo"
}
},
{
"urn": "urn:service:default:demo",
"entityType": "service",
"healthScore": null,
"healthStatus": "unknown",
"healthConfig": {},
"healthEnabled": false,
"attributes": {
"project": "demo",
"env": "prod"
}
}
]
}
}
}
],
"noGroupData": []
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-XXXX"
}