통합 카탈로그 토폴로지 조회¶
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"
}