콘텐츠로 이동

통합 카탈로그 엔터티 상세



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 또는 유효한 범위 배열)를 수정해야 하며, 엔터티 쿼리 파라미터를 반복 수정하는 것이 아닙니다.

문서 평가

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