콘텐츠로 이동

통합 카탈로그 토폴로지 엔터티 필드 정의



GET /api/v1/unified_catalog/topology/entity_fields

개요

현재 워크스페이스에서 조회 가능한 유형의 base 및 사용자 정의 필드 정의를 읽습니다.

호출 전 및 사용 단계

entityType을 전달하면 해당 유형의 fields를 반환합니다. 생략하거나 빈 문자열을 전달하면 entityType="", fields=[] 및 유형별로 구성된 entityTypes를 반환하며, 병합·중복 제거된 하나의 필드 테이블이 아닙니다. 단일 유형이 존재하지 않는 경우 일반적으로 []를 반환합니다. host/service는 예약된 entityStatus 옵션을 추가로 붙이므로, 결과가 비어 있지 않다는 것만으로 유형 존재 여부를 검증할 수 없으며 먼저 유형 목록을 조회해야 합니다.

필드 순서는 base properties 다음에 현재 워크스페이스의 customProperties가 오고, 이어서 entityType 내장 필드가 추가됩니다. host/service는 동일한 이름의 필드가 없을 때 entityStatus(online/offline)를 추가합니다. 제목은 요청에서 확인된 언어에 따라 현지화된 값을 선택하며, 반환된 텍스트는 요청 필드명으로 사용하지 않습니다. 이 페이지는 전체 Schema 기능/열거형 상세를 반환하지 않으며, 전체 편집 정보는 유형 상세의 원본 YAML을 사용합니다. 동일한 코드는 현재 워크스페이스 설정을 우선하며, 다른 워크스페이스의 사용자 정의 유형은 읽지 않습니다.

요청 헤더

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

Query 요청 파라미터

파라미터명 유형 필수 설명
entityType string 목록/통계에서는 선택 사항이며, 최상위 헬스 필드로 필터링·통계·정렬할 때는 업무상 필수입니다. 생성/수정 시 필수이며 공백 제거 후 비어 있지 않아야 합니다. 내보내기 시 필수입니다.
null 허용: True
예시: database
가져오기 또는 입력 방법: 엔터티 유형 목록의 items[].entityType에서 코드를 가져오며, 유형 UUID/표시 이름이 아닙니다.

파라미터 추가 설명

요청 파라미터 설명

파라미터명 type 필수 설명
entityType string 아니오 엔터티 유형 코드

호출 시 유의 사항

  • entityType을 전달하지 않거나 빈 문자열을 전달하면 현재 워크스페이스의 모든 엔터티 유형 필드를 반환합니다.
  • 특정 엔터티 유형의 필드 정의만 필요하다면 해당 entityType을 전달하여 반환 범위를 좁히는 것을 권장합니다.

요청 예시

curl --get 'https://openapi.guance.com/api/v1/unified_catalog/topology/entity_fields' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode entityType=database

응답

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

필드 유형 설명
content.entityType string 요청한 유형 코드이며, 전체 유형 모드에서는 빈 문자열입니다.
content.fields array<object> 단일 유형 필드 배열이며, 전체 유형 모드에서는 항상 []입니다.
content.fields[].key string 필드 코드이며, 이후 fields/filters/groupByFields에서 각 인터페이스 규칙에 따라 사용합니다.
content.fields[].title string 현지화된 제목이며, UIView title이 base 제목보다 우선하고 없으면 필드명으로 대체됩니다.
content.fields[].type string DataSchema 필드 유형이며, 기본값은 string이고 합성된 entityStatus는 enum입니다.
content.fields[].required boolean 필드 Schema의 필수 표시이며, 현재 조회 인터페이스에서 해당 속성을 반드시 입력해야 함을 의미하지는 않습니다.
content.fields[].systemReserved boolean 합성된 entityStatus에만 존재하며 true입니다.
content.fields[].options array<object> 합성된 entityStatus 등에서 반환되는 옵션이며, 일반 필드는 allowed_values의 전체 설정이 반환된다고 보장하지 않습니다.
content.fields[].options[].value string entityStatus는 online/offline입니다.
content.fields[].options[].label string 현지화된 옵션 텍스트입니다.
content.entityTypes array<object> 전체 유형 모드에서만 존재하며, 유형별로 필드를 나열합니다.
content.entityTypes[].entityType string 현재 조회 가능한 유형 코드입니다.
content.entityTypes[].fields array<object> 해당 유형의 필드입니다.
content.entityTypes[].fields[].key string 필드 코드이며, 이후 fields/filters/groupByFields에서 각 인터페이스 규칙에 따라 사용합니다.
content.entityTypes[].fields[].title string 현지화된 제목이며, UIView title이 base 제목보다 우선하고 없으면 필드명으로 대체됩니다.
content.entityTypes[].fields[].type string DataSchema 필드 유형이며, 기본값은 string이고 합성된 entityStatus는 enum입니다.
content.entityTypes[].fields[].required boolean 필드 Schema의 필수 표시이며, 현재 조회 인터페이스에서 해당 속성을 반드시 입력해야 함을 의미하지는 않습니다.
content.entityTypes[].fields[].systemReserved boolean 합성된 entityStatus에만 존재하며 true입니다.
content.entityTypes[].fields[].options array<object> 합성된 entityStatus 등에서 반환되는 옵션이며, 일반 필드는 allowed_values의 전체 설정이 반환된다고 보장하지 않습니다.
content.entityTypes[].fields[].options[].value string entityStatus는 online/offline입니다.
content.entityTypes[].fields[].options[].label string 현지화된 옵션 텍스트입니다.
content.declaration object 외부 공통 선언입니다.
{
  "code": 200,
  "content": {
    "entityType": "database",
    "fields": [
      {
        "key": "env",
        "title": "环境",
        "type": "string",
        "required": false
      },
      {
        "key": "entityType",
        "title": "实体类型",
        "type": "string",
        "required": true
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

entityType를 전달하지 않았을 때의 성공 구조:

{
  "code": 200,
  "content": {
    "entityType": "",
    "fields": [],
    "entityTypes": [
      {
        "entityType": "database",
        "fields": [
          {
            "key": "env",
            "title": "环境",
            "type": "string",
            "required": false
          },
          {
            "key": "entityType",
            "title": "实体类型",
            "type": "string",
            "required": true
          }
        ]
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

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

이 인터페이스는 유형 정의만 읽고 엔터티 데이터는 조회하지 않습니다. 존재하지 않는 코드는 빈 fields를 반환할 수 있으므로 필드 배열이 비어 있는 것을 404로 간주하지 마십시오. 과거 YAML/metadata가 손상되었거나 데이터베이스에 이상이 있으면 500이 발생할 수 있으며, traceId를 보관하고 관리자가 유형 원본 정의를 확인해야 합니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드명, 유형 및 값을 확인하십시오.
406 ft.InvalidParameter 현재 워크스페이스의 customProperties 필드가 base 필드와 충돌하거나 필드 YAML이 유효하지 않음 파라미터 {}가 유효하지 않음 관리자가 유형의 사용자 정의 필드를 수정하여 이름이 중복되지 않도록 하십시오. 파라미터 자체가 올바른 경우 필드명을 반복해서 바꾸지 마십시오.
500 ft.InternalServerError 다운스트림 조회 실패/시간 초과, 성공 데이터 형태 이상 또는 라벨/팀/시간 포맷 실패 내부 오류 조회 범위를 좁힌 후 적절히 재시도하십시오. 지속적으로 실패하면 traceId와 필터 조건을 보관하여 점검하며, 이번 쓰기로 인한 것으로 단정하지 마십시오.

문서 평가

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