통합 카탈로그 토폴로지 엔터티 필드 정의¶
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와 필터 조건을 보관하여 점검하며, 이번 쓰기로 인한 것으로 단정하지 마십시오. |