통합 카탈로그 엔터티 상세¶
POST /api/v1/unified_catalog/entity/get
개요¶
전체 URN으로 엔터티 상세, 소스 메타데이터 및 1홉 시스템 관계를 조회합니다.
호출 전 및 사용 단계¶
목록 items[].urn에서 대상을 가져오고, 반환된 원본 URN을 사용하여 후속 작업을 수행합니다. 존재하지 않으면 404를 반환하며, {}로 엔터티 존재를 표시하지 않습니다. 상세에는 teamInfo/tagsInfo와 1홉 systemRelationInfo가 포함됩니다. 관계 엔드포인트 요약의 attributes는 전체가 반환되지만, 엔드포인트 텔레메트리/소스 대형 필드는 추가로 제공하지 않습니다.
모든 엔터티 유형은 유효한 헬스 구성에 따라 처리되며, 백엔드 기록 정리 진행 상황에 의존하지 않습니다. system 유형 정책이 구성되지 않은 경우 기본값 default, 기타 유형은 구성되지 않은 경우 기본값 disabled입니다. 엔터티는 inherit가 유형을 상속하고, custom은 Func를 지정하며, disabled는 비활성화합니다. 유형이 비활성화되면 healthScore=null, healthStatus=unknown, healthUpdateAt=null을 반환하며, 헬스 필터/통계도 기록 결과가 아닌 비활성화 상태를 기준으로 합니다. 필터/정렬/통계의 최상위 헬스 필드에는 반드시 entityType을 명시해야 합니다.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 발급받아 입력합니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| urn | string | Y | 읽기/삭제 시 필수이며 앞뒤 공백을 제거한 후 비어 있지 않아야 합니다. 목록/통계에서는 선택적으로 정확히 일치 필터링할 수 있습니다. 수정 시 원본 URN을 명확히 입력하여 이름 변경 시 다른 엔터티가 생성되는 것을 방지할 것을 권장합니다. null 허용: False 예: urn:database:default:demo가져오기 또는 입력 방법: 이 워크스페이스 엔터티 목록의 items[].urn에서 가져오며, 전체 URN을 원본 그대로 사용하는 것을 우선합니다. |
파라미터 추가 설명¶
요청 파라미터 설명
| 파라미터명 | type | 필수 | 설명 |
|---|---|---|---|
| urn | string | 예 | 대상 엔터티의 고유 URN |
반환 결과 설명
- 엔터티 기본 정보,
attributes,teamInfo,tagsInfo를 반환합니다. systemRelationInfo는 현재 엔터티의 1홉 직접 시스템 관계 목록입니다.healthConfig/healthEnabled/healthScore/healthStatus/healthUpdateAt를 고정적으로 반환합니다. 모든 유형은 항상 유효한 구성에 따라 반환되며, 백엔드 readiness 정리 진행 상황에 의존하지 않습니다.
호출 시 유의 사항
systemRelationInfo는 재귀적으로 확장하지 않고 직접 관계만 반환합니다.systemRelationInfo에서 관계 양쪽 엔터티 요약의attributes는 전체가 반환됩니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/get' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"urn":"urn:database:default:demo"}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content | object | 대상 엔터티 상세입니다. |
| content.id | integer 또는 string 또는 null | 기본 엔터티 레코드 식별자이며 값이 없을 수 있습니다. 고객이 대상을 식별할 때는 urn을 사용합니다. |
| content.workspaceUUID | string | 인증 워크스페이스 UUID입니다. |
| content.urn | string | 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다. |
| content.entityType | string | 엔터티 유형 코드입니다. |
| content.provider | string | 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 따라 결정됩니다. |
| content.name | string | 엔터티 이름입니다. |
| content.displayName | string | 엔터티 표시 이름입니다. 비어 있을 수 있습니다. |
| content.attributes | object | 엔터티 동적 속성입니다. 목록에서는 쿼리 서비스가 프로젝션하고, 상세에서는 사용 가능한 전체 속성을 읽습니다. |
| content.attributes.필드명 | JSON | 해당 유형의 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 재정의 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다. |
| content.telemetrySelectors | array 또는 object | 기존 텔레메트리 연관 JSON입니다. 내부 빈 값은 {}로 정규화될 수 있으며, 항상 배열임을 보장하지 않습니다. |
| content.telemetrySelectors[] | JSON | 각 텔레메트리 연관 동적 항목이며 원래 구성대로 유지됩니다. 쿼리 결과가 아닙니다. |
| content.sourceMetadata | object | 소스 원본 메타데이터이며 목록에서는 빈 객체일 수 있습니다. 상세에서는 이 데이터를 명시적으로 요청하며, 구체적인 키는 소스에 따라 다릅니다. |
| content.sourceMetadata.필드명 | JSON | 소스 시스템의 사용자 정의 메타 정보이며, 범용 필수 프로토콜로 간주해서는 안 됩니다. |
| content.healthScore | integer 또는 null | 유효한 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스가 비활성화되면 null이며 0과 직접 같지 않습니다. |
| content.healthStatus | string | healthy/warning/critical/unknown. 헬스가 비활성화되면 unknown입니다. |
| content.healthUpdateAt | string 또는 null | 헬스 업데이트 시간이며 일반적으로 YYYY-MM-DD HH:mm:ss입니다. 비활성화/값 없음은 null입니다. |
| content.createdAt | string 또는 null | 생성 시간이며 일반적으로 YYYY-MM-DD HH:mm:ss이고 서비스 형식에 따라 반환됩니다. |
| content.updatedAt | string 또는 null | 최종 업데이트 시간이며 생성 시간과 같은 형식입니다. |
| content.healthConfig | object | 엔터티 재정의 정책이며 유형 정책의 복사본이 아닙니다. |
| content.healthConfig.mode | string | inherit/func/disabled. 기록에 func_id만 있는 경우 func로 정규화됩니다. |
| content.healthConfig.funcId | string | func 모드에서만 나타나는 함수 UUID입니다. |
| content.healthEnabled | boolean | 유형과 엔터티 구성을 종합한 유효 스위치입니다. 유형이 disabled이면 엔터티가 custom이어도 활성화할 수 없습니다. |
| content.entityStatus | string | online/offline. 이전 데이터는 기본값 online이며, 상태는 헬스 등급과 같지 않습니다. |
| content.lifecycleManaged | boolean | 엔터티 수명 주기 관리 대상인지 여부이며 기본값은 false입니다. |
| content.lastReportedAt | integer 또는 null | 최근 보고 Unix 초이며 값이 없으면 null입니다. |
| content.offlineAt | integer 또는 null | 오프라인 Unix 초이며 오프라인이 아니면 null입니다. |
| content.deleteAt | integer 또는 null | 수명 주기 정리 예정 Unix 초이며 예정이 없으면 null입니다. 이번 API 삭제 시간이 아닙니다. |
| content.statusUpdatedAt | integer 또는 null | 엔터티 상태 업데이트 시간 Unix 초이며 값이 없으면 null입니다. |
| content.teamInfo | array<object> | owner 기준으로 해석한 팀 요약입니다. 기록 참조를 찾을 수 없어도 가짜 팀을 구성하지 않습니다. |
| content.teamInfo[].uuid | string | 팀 group_ UUID입니다. |
| content.teamInfo[].type | string | 일반적으로 team입니다. |
| content.teamInfo[].name | string | 현재 팀 이름입니다. |
| content.teamInfo[].members | array | 팀 구성원 원본 JSON입니다. 구체적인 구성원 필드는 팀 관리 계약을 따르며, 이 페이지에서 전체 구성원 상세를 추가로 조회하지 않습니다. |
| content.teamInfo[].members[] | JSON | 팀이 저장한 구성원 요소이며 계정 식별자/객체일 수 있습니다. 팀 상세를 기준으로 합니다. |
| content.tagsInfo | array<object> | 현재 워크스페이스에 존재하는 태그 요약이며, 해석되지 않으면 []입니다. |
| content.tagsInfo[].name | string | 태그 이름입니다. |
| content.tagsInfo[].uuid | string | 태그 UUID입니다. |
| content.tagsInfo[].colour | string | 색상이며 값이 없으면 빈 문자열입니다. |
| content.tagsInfo[].scope | array<string> | 유효 범위 배열입니다. 누락된 기록 값은 [all]로 정규화되며, all은 다른 범위와 혼용할 수 없습니다. |
| content.tagsInfo[].scope[] | string | all/scene/monitor/dialing/security/infrastructure/catalog. 태그의 현재 구성에 따라 반환됩니다. |
| content.systemRelationInfo | array<object> | 1홉 직접 시스템 관계이며 재귀적으로 확장하지 않습니다. |
| content.systemRelationInfo[].id | integer 또는 string 또는 null | 관계 레코드 식별자입니다. |
| content.systemRelationInfo[].workspaceUUID | string | 소속 워크스페이스입니다. |
| content.systemRelationInfo[].sourceUrn | string | 소스 노드 URN입니다. |
| content.systemRelationInfo[].targetUrn | string | 대상 노드 URN입니다. |
| content.systemRelationInfo[].relationType | string | 관계 유형(예: contains/links)입니다. |
| content.systemRelationInfo[].컴포넌트 구성 키 | JSON | components 구성과 일치할 때 해당 동적 키를 추가하며, 기존 고정 관계 필드는 유지합니다. |
| content.systemRelationInfo[].sourceUrnInfo | object | 관계 엔드포인트 엔터티 요약이며 사용 가능한 attributes 전체를 포함합니다. 엔드포인트가 없으면 {}입니다. |
| content.systemRelationInfo[].sourceUrnInfo.id | integer 또는 string 또는 null | 기본 엔터티 레코드 식별자이며 값이 없을 수 있습니다. 고객이 대상을 식별할 때는 urn을 사용합니다. |
| content.systemRelationInfo[].sourceUrnInfo.workspaceUUID | string | 인증 워크스페이스 UUID입니다. |
| content.systemRelationInfo[].sourceUrnInfo.urn | string | 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다. |
| content.systemRelationInfo[].sourceUrnInfo.entityType | string | 엔터티 유형 코드입니다. |
| content.systemRelationInfo[].sourceUrnInfo.provider | string | 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 따라 결정됩니다. |
| content.systemRelationInfo[].sourceUrnInfo.name | string | 엔터티 이름입니다. |
| content.systemRelationInfo[].sourceUrnInfo.displayName | string | 엔터티 표시 이름입니다. 비어 있을 수 있습니다. |
| content.systemRelationInfo[].sourceUrnInfo.attributes | object | 엔터티 동적 속성입니다. 목록에서는 쿼리 서비스가 프로젝션하고, 상세에서는 사용 가능한 전체 속성을 읽습니다. |
| content.systemRelationInfo[].sourceUrnInfo.attributes.필드명 | JSON | 해당 유형의 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 재정의 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다. |
| content.systemRelationInfo[].sourceUrnInfo.healthScore | integer 또는 null | 유효한 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스가 비활성화되면 null이며 0과 직접 같지 않습니다. |
| content.systemRelationInfo[].sourceUrnInfo.healthStatus | string | healthy/warning/critical/unknown. 헬스가 비활성화되면 unknown입니다. |
| content.systemRelationInfo[].sourceUrnInfo.createdAt | string 또는 null | 생성 시간이며 일반적으로 YYYY-MM-DD HH:mm:ss이고 서비스 형식에 따라 반환됩니다. |
| content.systemRelationInfo[].sourceUrnInfo.updatedAt | string 또는 null | 최종 업데이트 시간이며 생성 시간과 같은 형식입니다. |
| content.systemRelationInfo[].sourceUrnInfo.entityStatus | string | online/offline. 이전 데이터는 기본값 online이며, 상태는 헬스 등급과 같지 않습니다. |
| content.systemRelationInfo[].sourceUrnInfo.lifecycleManaged | boolean | 엔터티 수명 주기 관리 대상인지 여부이며 기본값은 false입니다. |
| content.systemRelationInfo[].sourceUrnInfo.lastReportedAt | integer 또는 null | 최근 보고 Unix 초이며 값이 없으면 null입니다. |
| content.systemRelationInfo[].sourceUrnInfo.offlineAt | integer 또는 null | 오프라인 Unix 초이며 오프라인이 아니면 null입니다. |
| content.systemRelationInfo[].sourceUrnInfo.deleteAt | integer 또는 null | 수명 주기 정리 예정 Unix 초이며 예정이 없으면 null입니다. 이번 API 삭제 시간이 아닙니다. |
| content.systemRelationInfo[].sourceUrnInfo.statusUpdatedAt | integer 또는 null | 엔터티 상태 업데이트 시간 Unix 초이며 값이 없으면 null입니다. |
| content.systemRelationInfo[].targetUrnInfo | object | 관계 엔드포인트 엔터티 요약이며 사용 가능한 attributes 전체를 포함합니다. 엔드포인트가 없으면 {}입니다. |
| content.systemRelationInfo[].targetUrnInfo.id | integer 또는 string 또는 null | 기본 엔터티 레코드 식별자이며 값이 없을 수 있습니다. 고객이 대상을 식별할 때는 urn을 사용합니다. |
| content.systemRelationInfo[].targetUrnInfo.workspaceUUID | string | 인증 워크스페이스 UUID입니다. |
| content.systemRelationInfo[].targetUrnInfo.urn | string | 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다. |
| content.systemRelationInfo[].targetUrnInfo.entityType | string | 엔터티 유형 코드입니다. |
| content.systemRelationInfo[].targetUrnInfo.provider | string | 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 따라 결정됩니다. |
| content.systemRelationInfo[].targetUrnInfo.name | string | 엔터티 이름입니다. |
| content.systemRelationInfo[].targetUrnInfo.displayName | string | 엔터티 표시 이름입니다. 비어 있을 수 있습니다. |
| content.systemRelationInfo[].targetUrnInfo.attributes | object | 엔터티 동적 속성입니다. 목록에서는 쿼리 서비스가 프로젝션하고, 상세에서는 사용 가능한 전체 속성을 읽습니다. |
| content.systemRelationInfo[].targetUrnInfo.attributes.필드명 | JSON | 해당 유형의 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 재정의 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다. |
| content.systemRelationInfo[].targetUrnInfo.healthScore | integer 또는 null | 유효한 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스가 비활성화되면 null이며 0과 직접 같지 않습니다. |
| content.systemRelationInfo[].targetUrnInfo.healthStatus | string | healthy/warning/critical/unknown. 헬스가 비활성화되면 unknown입니다. |
| content.systemRelationInfo[].targetUrnInfo.createdAt | string 또는 null | 생성 시간이며 일반적으로 YYYY-MM-DD HH:mm:ss이고 서비스 형식에 따라 반환됩니다. |
| content.systemRelationInfo[].targetUrnInfo.updatedAt | string 또는 null | 최종 업데이트 시간이며 생성 시간과 같은 형식입니다. |
| content.systemRelationInfo[].targetUrnInfo.entityStatus | string | online/offline. 이전 데이터는 기본값 online이며, 상태는 헬스 등급과 같지 않습니다. |
| content.systemRelationInfo[].targetUrnInfo.lifecycleManaged | boolean | 엔터티 수명 주기 관리 대상인지 여부이며 기본값은 false입니다. |
| content.systemRelationInfo[].targetUrnInfo.lastReportedAt | integer 또는 null | 최근 보고 Unix 초이며 값이 없으면 null입니다. |
| content.systemRelationInfo[].targetUrnInfo.offlineAt | integer 또는 null | 오프라인 Unix 초이며 오프라인이 아니면 null입니다. |
| content.systemRelationInfo[].targetUrnInfo.deleteAt | integer 또는 null | 수명 주기 정리 예정 Unix 초이며 예정이 없으면 null입니다. 이번 API 삭제 시간이 아닙니다. |
| content.systemRelationInfo[].targetUrnInfo.statusUpdatedAt | integer 또는 null | 엔터티 상태 업데이트 시간 Unix 초이며 값이 없으면 null입니다. |
| content.declaration | object | 공통 선언입니다. |
{
"code": 200,
"content": {
"id": null,
"workspaceUUID": "wksp_example",
"urn": "urn:database:default:demo",
"entityType": "database",
"provider": "manual",
"name": "demo",
"displayName": "Demo database",
"attributes": {
"env": "prod",
"project": "demo"
},
"telemetrySelectors": {},
"sourceMetadata": {},
"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,
"teamInfo": [],
"tagsInfo": [],
"systemRelationInfo": [],
"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 | urn이 공백 제거 후 비어 있음 | 파라미터 {} 무효 |
현재 워크스페이스 목록에 있는 전체 URN을 전달하십시오. |
| 404 | ft.NotFoundEntity | 현재 워크스페이스에서 대상 엔터티를 찾지 못함 | 지정된 엔터티를 찾을 수 없음 | 워크스페이스, URN 및 수집/보고 완료 여부를 확인하십시오. 유형 UUID로 바꾸지 마십시오. |
| 500 | ft.InternalServerError | 다운스트림 쿼리 실패/시간 초과, 성공 데이터 형상 이상 또는 태그/팀/시간 포맷 실패 | 내부 오류 | 쿼리 범위를 줄인 후 적절히 재시도하십시오. 계속 실패하면 traceId와 필터 조건을 보존하여 조사하고, 이번 쓰기로 귀인하지 마십시오. |
| 406 | ft.ParameterValidationFailed | 저장된 태그 scope가 유효하지 않아 태그 요약 읽기 시 검증 실패 | invalid scope | message=invalid scope인 경우 관리자가 관련 태그의 기록 범위(all 또는 유효한 범위 배열)를 수정해야 하며, 엔터티 쿼리 파라미터를 반복 수정하는 것이 아닙니다. |