콘텐츠로 이동

통합 카탈로그 토폴로지 쿼리



POST /api/v1/unified_catalog/topology/query

개요

필터링된 시작점에서 카탈로그 엔터티 토폴로지를 확장하고 노드 속성으로 그룹화합니다.

호출 전 및 사용 단계

entityType/urn/providers/search/filters/orderBy는 시작점 엔터티 선택에 적용되며, 확장 후 다른 유형/소스의 노드가 나타날 수 있으므로 모든 반환 노드에 다시 필터링하는 것은 아닙니다. relationTypes는 관계 종류를 필터링합니다. 공개 Body에 maxDepth/nodeLimit이 선언되어 있지 않으며, 현재 어댑터는 기본 최대 깊이 10과 노드 제한 200을 사용합니다. 이러한 미선언 필드를 제출하여 결과 확대를 보장할 수 없습니다. 이 결과는 전체 워크스페이스의 완전한 그래프나 총 개수를 보장하지 않습니다.

groupByFields는 순서대로 다중 레벨 노드 그룹화를 수행하며, entityType/entityStatus는 최상위에서 읽고 나머지는 원시 attributes 키에서 읽습니다. 배열 속성은 하나의 노드가 여러 버킷에 포함될 수 있습니다. 그룹 내 data와 재귀 groupByLayers, noGroupData를 모두 순회해야 하며, 버킷 개수 합계를 고유 노드 수로 간주해서는 안 됩니다. 그룹화가 없으면 모든 노드가 noGroupData에 들어가며, 고립된 노드는 그룹 데이터에만 나타날 수도 있습니다. 관계 엔드포인트의 attributes는 전체 반환되며, 엔터티 상세의 소스 메타데이터/텔레메트리/팀 태그 요약은 추가되지 않습니다.

모든 엔터티 유형은 유효 헬스 구성에 따라 처리되며, 백그라운드 이력 정리 진행 상황에 의존하지 않습니다. system에 유형 정책이 구성되지 않은 경우 기본값은 default이고, 다른 유형은 구성되지 않은 경우 기본값이 disabled입니다. 엔터티는 inherit로 유형을 상속하고, custom은 Func를 지정하며, disabled는 비활성화합니다. 유형이 비활성화되면 healthScore=null, healthStatus=unknown, healthUpdateAt=null을 반환하며, 헬스 필터링/통계도 이력 결과가 아닌 비활성화 상태를 기준으로 합니다. 필터링/정렬/통계에서 최상위 헬스 필드를 사용할 때는 entityType을 명확히 지정해야 합니다.

요청 헤더

매개변수명 유형 필수 설명
DF-API-KEY string 예 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예: <DF-API-KEY>
가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 매개변수

매개변수명 유형 필수 설명
providers[*] string 배열 내 하나의 소스이며, 상위 배열을 생략하면 필터링하지 않습니다.
예: manual
가져오기 또는 입력 방법: 기존 단일 엔터티의 provider 값입니다.
filters.속성필드명 string 동적 키이며, 스칼라 후보 값 배열을 권장합니다. 임의의 DQL 표현식을 필드명으로 사용할 수 없습니다. urn/provider/entityType 및 healthStatus와 같은 최상위 내장 필드와 snake_case 별칭은 최상위에 유지되며, attributes/sourceMetadata/telemetrySelectors 객체 내부의 키는 평탄화됩니다.
예: ["prod"]
가져오기 또는 입력 방법: 현재 엔터티 attributes의 실제 필드명을 사용합니다. 복잡한 값 필터링의 의미는 저장된 필드 유형과 쿼리 서비스 기능에 따릅니다.
filters.속성필드명[*] string 동일 필드의 후보 값 하나입니다. 숫자/불리언은 원래 JSON 유형을 유지하며 null과 문자열 "null"을 혼동하지 마세요.
예: prod
가져오기 또는 입력 방법: 현재 필드 후보 값/기존 엔터티 값에서 가져옵니다.
relationTypes[*] string links는 일반적으로 종속을, contains는 일반적으로 포함을 의미하며, 엔터티 유형/표시명이 아닙니다. 공개 API에서는 강한 열거 검증을 하지 않으며, 다른 값은 쿼리 서비스 지원 여부에 따릅니다.
예: contains
가져오기 또는 입력 방법: 기존 관계 범주 식별자입니다.
groupByFields[*] string 공백 항목은 건너뜁니다. title/임의의 DQL이 아닙니다. 배열 값은 비어 있지 않은 스칼라만 중복 제거하여 사용하며, 객체/중첩 배열은 그룹 값으로 사용할 수 없습니다.
예: project
가져오기 또는 입력 방법: project/env와 같은 원시 속성 키 또는 entityType/entityStatus입니다.
entityType string 목록/통계에서는 선택 사항이며, 최상위 헬스 필드를 사용하여 필터링, 통계 또는 정렬할 때는 필수입니다. 생성/수정 시 필수이고 공백 제거 후 비어 있지 않아야 하며, 내보내기 시 필수입니다.
null 허용: False
예: database
가져오기 또는 입력 방법: 엔터티 유형 목록의 items[].entityType에서 코드를 가져오며, 유형 UUID/표시명이 아닙니다.
filters json 선택적 객체이며, {}는 추가 필터링이 없습니다. 원시 속성 키 env는 attributes.env로 변환되며, 명시적 attributes.entityType은 최상위 entityType으로 처리되지 않습니다. 동일 필드의 여러 후보 값은 배열에 넣고, 서로 다른 필드는 쿼리 서비스가 조합합니다. 헬스 필드에는 별도의 유효 비활성화 상태가 있으며, 사용법을 참고하세요.
null 허용: False
예: {"env": ["prod"]}
가져오기 또는 입력 방법: 필드명은 유형 DataSchema/속성 또는 토폴로지 필드 목록에서 가져오며, 값은 필드 통계/기존 엔터티에서 가져옵니다.
groupByFields array 선택 사항이며, 배열 순서가 다중 레벨 그룹화를 결정합니다. []/생략 시 모든 반환 노드가 noGroupData에 들어갑니다. entityType/entityStatus 외에는 attributes의 원래 키로 읽으며, attributes. 접두사를 자동으로 제거하지 않습니다. 배열 속성은 동일 노드를 여러 버킷에 넣을 수 있고, 값이 없으면 이후 레벨에서 시도하며, 모든 값이 없으면 noGroupData에 들어갑니다.
null 허용: False
예: ["project", "env"]
가져오기 또는 입력 방법: 엔터티 attributes에 이미 있는 필드명에서 그룹화 대상을 선택하며, entityType/entityStatus를 내장 지원합니다.
orderBy string 선택 사항이며, 기본 정렬은 쿼리 서비스가 updatedAt 기준으로 처리합니다. 헬스 정렬에는 entityType이 필요합니다. 유형에서 헬스를 비활성화한 경우 헬스 정렬은 updatedAt desc로 대체되며, 이력 헬스 값으로 정렬하지 않습니다.
null 허용: False
예: updatedAt
가져오기 또는 입력 방법: 유형 뷰/필드 인터페이스에서 정렬 가능한 필드를 선택하며, updatedAt/name/healthScore와 같은 내장 필드와 속성의 경우 attributes.env를 사용합니다.
providers array 선택적 소스 배열이며, 비어 있지 않으면 provider보다 우선합니다. []는 소스 필터를 추가하지 않으며, 빈 소스만 선택하는 것이 아닙니다. 공개 배열은 항목별 문자열 검증이 선언되어 있지 않으므로 실제 문자열만 사용하는 것을 권장합니다.
null 허용: False
예: ["manual"]
가져오기 또는 입력 방법: field_value/count의 provider 후보 버킷에서 실제 소스 값을 가져옵니다.
relationTypes array 선택 사항이며, 생략/[]는 빈 목록을 전달하여 쿼리 서비스가 기본 범위를 처리하며, 하나의 관계만 가져오는 것을 보장하지 않습니다. 여러 값은 관계 범주 집합으로 사용되며 관계 방향을 변경하지 않습니다.
null 허용: False
예: ["links", "contains"]
가져오기 또는 입력 방법: 기존 관계의 relationType에서 값을 가져옵니다. 이 제품의 엔터티 편집은 links/contains를 생성합니다.
search string 토폴로지 쿼리 시 시작점 엔터티의 URN/name/display_name을 검색합니다. filter_options에서는 후보 값 키워드에 대한 이전 버전 호환 매개변수이며, fieldValue가 비어 있지 않으면 우선합니다. 두 시나리오를 혼동하지 마세요.
null 허용: False
예: demo
가져오기 또는 입력 방법: 호출자가 검색 키워드를 입력합니다.
urn string 선택적 시작점 엔터티 URN이며, 엔터티 목록에서 가져옵니다. 전달하지 않으면 다른 조건으로 시작점을 선택할 수 있습니다. 해당 노드만 엄격히 반환하는 것이 아니며, 관계 확장 시 인접한 유형/소스 노드가 포함됩니다.
null 허용: False
예: urn:database:default:demo
가져오기 또는 입력 방법: 현재 워크스페이스 엔터티 목록의 items[].urn에서 가져오며, 전체 URN을 원본 그대로 사용하는 것을 우선합니다.

매개변수 추가 설명

요청 매개변수 설명

매개변수명 유형 필수 설명
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 --request POST 'https://openapi.guance.com/api/v1/unified_catalog/topology/query' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"entityType":"service","filters":{"project":["demo"]},"relationTypes":["links","contains"],"groupByFields":["project"]}'

응답

HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content.items array<object> 토폴로지 관계 엣지 배열이며, 관계가 없으면 []입니다. 페이지네이션 totalCount는 포함하지 않습니다.
content.items[].id integer 또는 string 또는 null 관계 식별자로 보조 조회한 레코드 식별자이며, 일치하지 않으면 null일 수 있습니다.
content.items[].workspaceUUID string 소속 워크스페이스입니다.
content.items[].sourceUrn string 소스 노드 URN입니다.
content.items[].targetUrn string 대상 노드 URN입니다.
content.items[].relationType string 관계 범주이며, 예: links/contains.
content.items[].sourceUrnInfo object 관계 엔드포인트 요약이며, 찾지 못하면 {}일 수 있고 attributes를 전체 사용할 수 있습니다. teamInfo/tagsInfo/텔레메트리/소스 대형 필드는 추가되지 않습니다.
content.items[].sourceUrnInfo.id integer 또는 string 또는 null 하위 엔터티 레코드 식별자이며, 값이 없을 수 있습니다. 고객 식별에는 urn을 사용합니다.
content.items[].sourceUrnInfo.workspaceUUID string 인증 워크스페이스 UUID입니다.
content.items[].sourceUrnInfo.urn string 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다.
content.items[].sourceUrnInfo.entityType string 엔터티 유형 코드입니다.
content.items[].sourceUrnInfo.provider string 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 따라 결정됩니다.
content.items[].sourceUrnInfo.name string 엔터티 이름입니다.
content.items[].sourceUrnInfo.displayName string 엔터티 표시명이며, 비어 있을 수 있습니다.
content.items[].sourceUrnInfo.attributes object 엔터티 동적 속성이며, 이 토폴로지는 사용 가능한 모든 속성을 반환합니다.
content.items[].sourceUrnInfo.attributes.필드명 JSON 해당 유형 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 재정의 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다.
content.items[].sourceUrnInfo.healthScore integer 또는 null 유효 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스가 비활성화되면 null이며 0과 동일하지 않습니다.
content.items[].sourceUrnInfo.healthStatus string healthy/warning/critical/unknown이며, 헬스가 비활성화되면 unknown입니다.
content.items[].sourceUrnInfo.healthUpdateAt string 또는 null 헬스 업데이트 시간이며, 일반적으로 YYYY-MM-DD HH:mm:ss 형식입니다. 비활성화/값 없음이면 null입니다.
content.items[].sourceUrnInfo.createdAt string 또는 null 생성 시간이며, 일반적으로 YYYY-MM-DD HH:mm:ss 형식이고 서비스 형식에 따라 반환됩니다.
content.items[].sourceUrnInfo.updatedAt string 또는 null 마지막 업데이트 시간이며, 생성 시간과 같은 형식입니다.
content.items[].sourceUrnInfo.healthConfig object 엔터티 재정의 정책이며, 유형 정책의 복사본이 아닙니다.
content.items[].sourceUrnInfo.healthConfig.mode string inherit/func/disabled이며, 이전 데이터의 func_id만 func로 정규화됩니다.
content.items[].sourceUrnInfo.healthConfig.funcId string func 모드에서만 나타나는 함수 UUID입니다.
content.items[].sourceUrnInfo.healthEnabled boolean 유형과 엔터티 구성을 종합한 유효 스위치이며, 유형이 disabled이면 엔터티 custom도 활성화할 수 없습니다.
content.items[].sourceUrnInfo.entityStatus string online/offline이며, 이전 데이터는 기본값 online입니다. 상태는 헬스 등급과 같지 않습니다.
content.items[].sourceUrnInfo.lifecycleManaged boolean 엔터티 수명 주기 관리 대상인지 여부이며, 기본값은 false입니다.
content.items[].sourceUrnInfo.lastReportedAt integer 또는 null 최근 보고 Unix 초이며, 값이 없으면 null입니다.
content.items[].sourceUrnInfo.offlineAt integer 또는 null 오프라인 Unix 초이며, 오프라인이 아니면 null입니다.
content.items[].sourceUrnInfo.deleteAt integer 또는 null 수명 주기 정리 예정 Unix 초이며, 예정이 없으면 null입니다. 이번 API 삭제 시간이 아닙니다.
content.items[].sourceUrnInfo.statusUpdatedAt integer 또는 null 엔터티 상태 업데이트 Unix 초이며, 값이 없으면 null입니다.
content.items[].targetUrnInfo object 관계 엔드포인트 요약이며, 찾지 못하면 {}일 수 있고 attributes를 전체 사용할 수 있습니다. teamInfo/tagsInfo/텔레메트리/소스 대형 필드는 추가되지 않습니다.
content.items[].targetUrnInfo.id integer 또는 string 또는 null 하위 엔터티 레코드 식별자이며, 값이 없을 수 있습니다. 고객 식별에는 urn을 사용합니다.
content.items[].targetUrnInfo.workspaceUUID string 인증 워크스페이스 UUID입니다.
content.items[].targetUrnInfo.urn string 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다.
content.items[].targetUrnInfo.entityType string 엔터티 유형 코드입니다.
content.items[].targetUrnInfo.provider string 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 따라 결정됩니다.
content.items[].targetUrnInfo.name string 엔터티 이름입니다.
content.items[].targetUrnInfo.displayName string 엔터티 표시명이며, 비어 있을 수 있습니다.
content.items[].targetUrnInfo.attributes object 엔터티 동적 속성이며, 이 토폴로지는 사용 가능한 모든 속성을 반환합니다.
content.items[].targetUrnInfo.attributes.필드명 JSON 해당 유형 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 재정의 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다.
content.items[].targetUrnInfo.healthScore integer 또는 null 유효 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스가 비활성화되면 null이며 0과 동일하지 않습니다.
content.items[].targetUrnInfo.healthStatus string healthy/warning/critical/unknown이며, 헬스가 비활성화되면 unknown입니다.
content.items[].targetUrnInfo.healthUpdateAt string 또는 null 헬스 업데이트 시간이며, 일반적으로 YYYY-MM-DD HH:mm:ss 형식입니다. 비활성화/값 없음이면 null입니다.
content.items[].targetUrnInfo.createdAt string 또는 null 생성 시간이며, 일반적으로 YYYY-MM-DD HH:mm:ss 형식이고 서비스 형식에 따라 반환됩니다.
content.items[].targetUrnInfo.updatedAt string 또는 null 마지막 업데이트 시간이며, 생성 시간과 같은 형식입니다.
content.items[].targetUrnInfo.healthConfig object 엔터티 재정의 정책이며, 유형 정책의 복사본이 아닙니다.
content.items[].targetUrnInfo.healthConfig.mode string inherit/func/disabled이며, 이전 데이터의 func_id만 func로 정규화됩니다.
content.items[].targetUrnInfo.healthConfig.funcId string func 모드에서만 나타나는 함수 UUID입니다.
content.items[].targetUrnInfo.healthEnabled boolean 유형과 엔터티 구성을 종합한 유효 스위치이며, 유형이 disabled이면 엔터티 custom도 활성화할 수 없습니다.
content.items[].targetUrnInfo.entityStatus string online/offline이며, 이전 데이터는 기본값 online입니다. 상태는 헬스 등급과 같지 않습니다.
content.items[].targetUrnInfo.lifecycleManaged boolean 엔터티 수명 주기 관리 대상인지 여부이며, 기본값은 false입니다.
content.items[].targetUrnInfo.lastReportedAt integer 또는 null 최근 보고 Unix 초이며, 값이 없으면 null입니다.
content.items[].targetUrnInfo.offlineAt integer 또는 null 오프라인 Unix 초이며, 오프라인이 아니면 null입니다.
content.items[].targetUrnInfo.deleteAt integer 또는 null 수명 주기 정리 예정 Unix 초이며, 예정이 없으면 null입니다. 이번 API 삭제 시간이 아닙니다.
content.items[].targetUrnInfo.statusUpdatedAt integer 또는 null 엔터티 상태 업데이트 Unix 초이며, 값이 없으면 null입니다.
content.groupInfo object 반환된 엔터티 노드를 기반으로 구성된 그룹이며, 관계 엣지 수 그룹화가 아닙니다.
content.groupInfo.groupByLayers array<object> 최상위 그룹화 레이어이며, []는 그룹화 없음입니다.
content.groupInfo.groupByLayers[].groupByField string 현재 그룹화 필드입니다.
content.groupInfo.groupByLayers[].groupByData object 그룹 값 문자열을 동적 키로 사용하는 버킷 매핑입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값 object 해당 그룹의 노드 데이터 및 선택적 하위 그룹입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data array<object> 현재 레이어에서 하위 그룹으로 들어가지 않은 노드이며, 리프 레이어에서는 해당 그룹의 모든 노드입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.groupByLayers array<object> 선택적 다음 레벨 그룹화이며, 재귀 구조는 groupInfo.groupByLayers와 같습니다. 여기에 포함된 노드를 무시할 수 없습니다.
content.groupInfo.noGroupData array<object> 모든 그룹화 필드와 일치하지 않은 노드이며, groupByFields가 없으면 반환된 모든 노드를 저장합니다.
content.declaration object 외부 공통 선언만 해당합니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].urn string 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].entityType string 엔터티 유형 코드입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].provider string 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 따라 결정됩니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].name string 엔터티 이름입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].displayName string 엔터티 표시명이며, 비어 있을 수 있습니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].attributes object 엔터티 동적 속성이며, 이 토폴로지는 사용 가능한 모든 속성을 반환합니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].attributes.필드명 JSON 해당 유형 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 재정의 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].healthScore integer 또는 null 유효 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스가 비활성화되면 null이며 0과 동일하지 않습니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].healthStatus string healthy/warning/critical/unknown이며, 헬스가 비활성화되면 unknown입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].healthUpdateAt string 또는 null 헬스 업데이트 시간이며, 일반적으로 YYYY-MM-DD HH:mm:ss 형식입니다. 비활성화/값 없음이면 null입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].healthConfig object 엔터티 재정의 정책이며, 유형 정책의 복사본이 아닙니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].healthConfig.mode string inherit/func/disabled이며, 이전 데이터의 func_id만 func로 정규화됩니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].healthConfig.funcId string func 모드에서만 나타나는 함수 UUID입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].healthEnabled boolean 유형과 엔터티 구성을 종합한 유효 스위치이며, 유형이 disabled이면 엔터티 custom도 활성화할 수 없습니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].entityStatus string online/offline이며, 이전 데이터는 기본값 online입니다. 상태는 헬스 등급과 같지 않습니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].lifecycleManaged boolean 엔터티 수명 주기 관리 대상인지 여부이며, 기본값은 false입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].lastReportedAt integer 또는 null 최근 보고 Unix 초이며, 값이 없으면 null입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].offlineAt integer 또는 null 오프라인 Unix 초이며, 오프라인이 아니면 null입니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].deleteAt integer 또는 null 수명 주기 정리 예정 Unix 초이며, 예정이 없으면 null입니다. 이번 API 삭제 시간이 아닙니다.
content.groupInfo.groupByLayers[].groupByData.그룹값.data[].statusUpdatedAt integer 또는 null 엔터티 상태 업데이트 Unix 초이며, 값이 없으면 null입니다.
content.groupInfo.noGroupData[].urn string 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다.
content.groupInfo.noGroupData[].entityType string 엔터티 유형 코드입니다.
content.groupInfo.noGroupData[].provider string 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 따라 결정됩니다.
content.groupInfo.noGroupData[].name string 엔터티 이름입니다.
content.groupInfo.noGroupData[].displayName string 엔터티 표시명이며, 비어 있을 수 있습니다.
content.groupInfo.noGroupData[].attributes object 엔터티 동적 속성이며, 이 토폴로지는 사용 가능한 모든 속성을 반환합니다.
content.groupInfo.noGroupData[].attributes.필드명 JSON 해당 유형 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 재정의 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다.
content.groupInfo.noGroupData[].healthScore integer 또는 null 유효 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스가 비활성화되면 null이며 0과 동일하지 않습니다.
content.groupInfo.noGroupData[].healthStatus string healthy/warning/critical/unknown이며, 헬스가 비활성화되면 unknown입니다.
content.groupInfo.noGroupData[].healthUpdateAt string 또는 null 헬스 업데이트 시간이며, 일반적으로 YYYY-MM-DD HH:mm:ss 형식입니다. 비활성화/값 없음이면 null입니다.
content.groupInfo.noGroupData[].healthConfig object 엔터티 재정의 정책이며, 유형 정책의 복사본이 아닙니다.
content.groupInfo.noGroupData[].healthConfig.mode string inherit/func/disabled이며, 이전 데이터의 func_id만 func로 정규화됩니다.
content.groupInfo.noGroupData[].healthConfig.funcId string func 모드에서만 나타나는 함수 UUID입니다.
content.groupInfo.noGroupData[].healthEnabled boolean 유형과 엔터티 구성을 종합한 유효 스위치이며, 유형이 disabled이면 엔터티 custom도 활성화할 수 없습니다.
content.groupInfo.noGroupData[].entityStatus string online/offline이며, 이전 데이터는 기본값 online입니다. 상태는 헬스 등급과 같지 않습니다.
content.groupInfo.noGroupData[].lifecycleManaged boolean 엔터티 수명 주기 관리 대상인지 여부이며, 기본값은 false입니다.
content.groupInfo.noGroupData[].lastReportedAt integer 또는 null 최근 보고 Unix 초이며, 값이 없으면 null입니다.
content.groupInfo.noGroupData[].offlineAt integer 또는 null 오프라인 Unix 초이며, 오프라인이 아니면 null입니다.
content.groupInfo.noGroupData[].deleteAt integer 또는 null 수명 주기 정리 예정 Unix 초이며, 예정이 없으면 null입니다. 이번 API 삭제 시간이 아닙니다.
content.groupInfo.noGroupData[].statusUpdatedAt integer 또는 null 엔터티 상태 업데이트 Unix 초이며, 값이 없으면 null입니다.
{
  "code": 200,
  "content": {
    "items": [
      {
        "id": null,
        "workspaceUUID": "wksp_example",
        "sourceUrn": "urn:service:default:api",
        "targetUrn": "urn:database:default:demo",
        "relationType": "links",
        "sourceUrnInfo": {
          "id": null,
          "workspaceUUID": "wksp_example",
          "urn": "urn:service:default:api",
          "entityType": "service",
          "provider": "manual",
          "name": "api",
          "displayName": "API",
          "attributes": {
            "project": "demo",
            "env": "prod"
          },
          "healthScore": null,
          "healthStatus": "unknown",
          "healthUpdateAt": null,
          "createdAt": "2026-11-18 10:00:00",
          "updatedAt": "2026-11-18 10:00:00",
          "healthConfig": {
            "mode": "inherit"
          },
          "healthEnabled": false,
          "entityStatus": "online",
          "lifecycleManaged": false,
          "lastReportedAt": null,
          "offlineAt": null,
          "deleteAt": null,
          "statusUpdatedAt": null
        },
        "targetUrnInfo": {
          "id": null,
          "workspaceUUID": "wksp_example",
          "urn": "urn:database:default:demo",
          "entityType": "database",
          "provider": "manual",
          "name": "demo",
          "displayName": "Demo database",
          "attributes": {
            "project": "demo"
          },
          "healthScore": null,
          "healthStatus": "unknown",
          "healthUpdateAt": null,
          "createdAt": "2026-11-18 10:00:00",
          "updatedAt": "2026-11-18 10:00:00",
          "healthConfig": {
            "mode": "inherit"
          },
          "healthEnabled": false,
          "entityStatus": "online",
          "lifecycleManaged": false,
          "lastReportedAt": null,
          "offlineAt": null,
          "deleteAt": null,
          "statusUpdatedAt": null
        }
      }
    ],
    "groupInfo": {
      "groupByLayers": [
        {
          "groupByField": "project",
          "groupByData": {
            "demo": {
              "data": [
                {
                  "urn": "urn:service:default:api",
                  "entityType": "service",
                  "provider": "manual",
                  "name": "api",
                  "displayName": "API",
                  "attributes": {
                    "project": "demo",
                    "env": "prod"
                  },
                  "healthScore": null,
                  "healthStatus": "unknown",
                  "healthUpdateAt": null,
                  "healthConfig": {
                    "mode": "inherit"
                  },
                  "healthEnabled": false,
                  "entityStatus": "online",
                  "lifecycleManaged": false,
                  "lastReportedAt": null,
                  "offlineAt": null,
                  "deleteAt": null,
                  "statusUpdatedAt": null
                },
                {
                  "urn": "urn:database:default:demo",
                  "entityType": "database",
                  "provider": "manual",
                  "name": "demo",
                  "displayName": "Demo database",
                  "attributes": {
                    "project": "demo"
                  },
                  "healthScore": null,
                  "healthStatus": "unknown",
                  "healthUpdateAt": null,
                  "healthConfig": {
                    "mode": "inherit"
                  },
                  "healthEnabled": false,
                  "entityStatus": "online",
                  "lifecycleManaged": false,
                  "lastReportedAt": null,
                  "offlineAt": null,
                  "deleteAt": null,
                  "statusUpdatedAt": null
                }
              ]
            }
          }
        }
      ],
      "noGroupData": []
    },
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.

다운스트림 오류는 Kodo 공유 매핑을 따르며, 4xx는 실제 HTTP 및 ft.KodoCommonApiErr 또는 매핑된 비즈니스 코드를 반환할 수 있습니다. 모든 실패가 406으로 변환되는 것은 아닙니다. 전달되지 않은 5xx/연결 예외/성공 결과 구조 불일치는 최종적으로 500 ft.InternalServerError가 됩니다. errorCode/message/traceId를 유지하고 읽기 또는 쓰기 단계에 따라 처리하세요. 성공 HTTP가 엔터티의 실제 가시성 검증을 대체할 수는 없습니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방식
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 매개변수 파싱 실패 매개변수 위치, 필드명, 유형 및 값을 확인하세요.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정하세요.
400 ft.JsonFormatError Body 최상위가 JSON 객체가 아님 일부 json 파일 형식 오류 예시에 따라 객체를 제출하고 배열/문자열을 사용하지 마세요.
406 ft.InvalidParameter 헬스 filters/orderBy에서 entityType을 단일하게 명확히 지정하지 않음 매개변수 {}가 유효하지 않음 단일 유형 코드를 입력하고, 비활성화 상태는 null/unknown으로 처리하며, 혼합 유형의 이력 헬스 값을 사용하지 마세요.
500 ft.InternalServerError 다운스트림 쿼리 실패/시간 초과, 성공 데이터 형상 이상 또는 태그/팀/시간 형식 지정 실패 내부 오류 쿼리 범위를 좁힌 후 적절히 재시도하세요. 지속적으로 실패하면 traceId와 필터 조건을 유지하여 조사하고, 이번 쓰기로 인한 것으로 귀인하지 마세요.

문서 평가

이 페이지가 도움이 되었나요?