통합 카탈로그 토폴로지 필드 필터 옵션¶
POST /api/v1/unified_catalog/topology/filter_options
개요¶
지정한 필드에 따라 필터링 가능한 후보 값, 사람이 읽을 수 있는 레이블 및 개수를 조회합니다.
호출 전 및 사용 단계¶
fields 반환 키는 요청 표기를 유지합니다. 접두사 없는 env와 attributes.env는 동등하게 조회되지만, 반환 시에는 각각 요청 키로 다시 채워집니다. 접두사 없는 owner는 추가로 과거 계정/팀 UUID를 이름으로 변환하려고 시도하며, 찾지 못하면 원래 값으로 대체합니다. 이름으로 저장된 owner도 원래 이름을 유지하며, 모든 값이 group_ UUID임을 보장하지는 않습니다. 각 value는 Python str에 따라 문자열로 변환됩니다. 예: null→"None", true→"True", 숫자 3→"3"이며, count는 음수가 아닙니다. 엔터티의 field_value/count가 JSON 값 유형을 유지하는 것과 다릅니다.
filters는 엔터티 집합을 제한하고, fieldValue 또는 호환용 search가 후보 값을 필터링합니다. 둘 다 비어 있지 않으면 fieldValue가 우선하며, 엔터티 전체 텍스트 search는 수행하지 않습니다. 모든 fields가 공백이면 {}로 성공할 수 있습니다. 후보는 개수 내림차순으로 정렬되며, owner는 표시 레이블 기준으로 추가 정렬됩니다. 페이지네이션 API가 아닙니다.
모든 엔터티 유형은 유효한 헬스 구성에 따라 처리되며, 백그라운드의 과거 정리 진행 상황에 의존하지 않습니다. 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 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| filters.속성 필드명 | string | 동적 키이며, 스칼라 후보 값 배열을 권장합니다. 임의의 DQL 표현식을 필드 이름으로 사용할 수 없습니다. urn/provider/entityType 및 healthStatus와 같은 최상위 내장 필드와 snake_case 별칭은 최상위에 유지됩니다. attributes/sourceMetadata/telemetrySelectors 객체 내부 키는 평탄화됩니다. 예: ["prod"]가져오기 또는 입력 방법: 현재 엔터티 attributes의 실제 필드 이름을 사용합니다. 복잡한 값 필터링 의미는 저장된 필드 유형과 쿼리 서비스 기능을 기준으로 합니다. |
|
| filters.속성 필드명[*] | string | 동일 필드의 후보 값 하나입니다. 숫자/부울은 원래 JSON 유형을 유지하며, null과 문자열 null을 혼동하지 마세요. 예: prod가져오기 또는 입력 방법: 현재 필드의 후보 값/기존 엔터티 값에서 가져옵니다. |
|
| fields[*] | string | 필드 이름은 제목이 아니며 DQL도 아닙니다. attributes.entityType과 최상위 entityType은 독립적이며 버킷을 공유하지 않습니다. owner(베어 키)는 추가로 ID/팀 레이블을 해석하고, attributes.owner는 일반 버킷팅만 수행합니다. 예: env가져오기 또는 입력 방법: 단일 속성/내장 필드 이름입니다. 예: env, attributes.env, provider, healthStatus. |
|
| entityType | string | 목록/통계에서는 선택 사항입니다. 최상위 헬스 필드를 사용하여 필터링, 통계 또는 정렬할 때는 비즈니스상 필수입니다. 생성/수정 시 필수이며 공백 제거 후 비어 있지 않아야 합니다. 내보내기 시 필수입니다. null 허용: False 예: database가져오기 또는 입력 방법: 엔터티 유형 목록의 items[].entityType에서 코드를 가져옵니다. 유형 UUID/표시 이름이 아닙니다. |
|
| fieldValue | string | filter_options에서는 선택 사항이며, 비어 있지 않으면 search보다 우선합니다. 후보 버킷만 필터링하며 엔터티 전체 텍스트 검색이 아닙니다. 빈 문자열이면 search로 대체하고, 둘 다 비어 있으면 후보를 필터링하지 않습니다. null 허용: False 예: prod가져오기 또는 입력 방법: 사용자가 입력한 후보 값 키워드입니다. |
|
| fields | array | Y | 필수 1..64개 항목이며, 공백 항목은 건너뛰고 완전히 동일한 키는 중복 제거합니다. 접두사 없는 env와 attributes.env는 조회 시 동일 필드로 병합되지만, 반환 시에는 각각 요청 키로 다시 채워집니다. 모든 항목이 공백이면 {}를 반환하며, 일치 항목 없음 오류를 보고하지 않습니다. 헬스 필드에는 entityType이 필요합니다. null 허용: False 최대 길이: 64 최소 길이: 1 예: ["env", "owner"]가져오기 또는 입력 방법: entity_fields의 fields[].key 또는 기존 엔터티의 내장 필드에서 이름을 가져옵니다. |
| filters | json | 선택적 객체이며 {}는 추가 필터가 없습니다. 접두사 없는 속성 키 env는 attributes.env로 변환되며, 명시적 attributes.entityType은 최상위 entityType으로 처리되지 않습니다. 동일 필드의 여러 후보 값은 배열에 넣습니다. 서로 다른 필드는 쿼리 서비스에서 조합합니다. 헬스 필드에는 별도의 유효 비활성화 상태가 있으며, 사용법을 참고하세요. null 허용: False 예: {"env": ["prod"]}가져오기 또는 입력 방법: 필드 이름은 유형 DataSchema/속성 또는 토폴로지 필드 목록에서 가져오며, 값은 필드 통계/기존 엔터티에서 가져옵니다. |
|
| search | string | 토폴로지 쿼리 시 검색 시작 엔터티 URN/name/display_name입니다. filter_options에서는 후보 값 키워드에 대한 이전 버전 호환 파라미터이며, fieldValue가 비어 있지 않으면 우선합니다. 두 시나리오를 혼동하지 마세요. null 허용: False 예: demo가져오기 또는 입력 방법: 호출자가 입력한 쿼리 키워드입니다. |
파라미터 추가 설명¶
요청 파라미터 설명
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| entityType | string | 아니요 | 엔터티 유형 코드입니다. 헬스 필드 필터 옵션을 요청하거나 헬스 필드로 필터링할 때 필수입니다. |
| fields | array[string] | 예 | 필터 옵션을 반환할 필드 목록이며, 최대 64개 항목입니다. |
| filters | json | 아니요 | 선택한 필터 조건입니다. |
| search | string | 아니요 | 후보 값 검색의 호환 파라미터이며, 새 호출자는 fieldValue 사용을 권장합니다. |
| fieldValue | string | 아니요 | 후보 값만 필터링합니다. search와 함께 전달하면 우선 사용됩니다. |
호출 시 주의 사항
fields는 여러 필드를 전달할 수 있으며, API는 각 필드의 선택 가능한 값을 각각 반환합니다.- 필드가
owner이면 반환 결과를 최대한 팀에서 읽을 수 있는 이름으로 해석합니다. filters는 연동 필터링 시나리오에 사용할 수 있습니다.fields또는filters가 헬스 필드를 포함하면entityType이 필수입니다. 유형이 disabled이면 유효 비활성화 상태에 따라 후보 값을 생성합니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/topology/filter_options' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"entityType":"database","fields":["env","owner"],"filters":{},"fieldValue":""}'
응답¶
HTTP 200, application/json입니다. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.요청 필드명 | array<object> | 각 유효한 요청 필드에 대응하는 후보 배열입니다. 후보가 없으면 []이며, 동적 필드 이름은 요청과 동일합니다. |
| content.요청 필드명[].label | string | 사람이 읽을 수 있는 텍스트입니다. 베어 owner는 팀/ID 이름으로 해석될 수 있으며, 그 외에는 값 문자열입니다. |
| content.요청 필드명[].value | string | 필터 제출에 사용하는 값 문자열입니다. owner는 UUID 또는 원래 이름일 수 있으며, 현재 실제 엔터티 속성을 따릅니다. |
| content.요청 필드명[].count | integer | 후보 값에 대응하는 엔터티 수입니다. |
| content.declaration | object | 비어 있지 않은 결과에만 공통 선언이 삽입됩니다. 완전한 {}는 여전히 빈 객체입니다. |
{
"code": 200,
"content": {
"env": [
{
"label": "prod",
"value": "prod",
"count": 12
}
],
"owner": [
{
"label": "DBA",
"value": "group_example",
"count": 3
}
],
"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 | 헬스 필드 통계/헬스 필터링 시 entityType을 지정하지 않았거나 통계 필드가 유효하지 않음 | 파라미터 {}가 유효하지 않음 |
유형 코드를 입력하고 필드 인터페이스/실제 속성 키를 사용합니다. |
| 500 | ft.InternalServerError | 다운스트림 쿼리 실패/시간 초과, 성공 데이터 형태 이상 또는 레이블/팀/시간 형식 지정 실패 | 내부 오류 | 쿼리 범위를 줄인 후 적절히 재시도합니다. 지속적으로 실패하면 traceId와 필터 조건을 유지하여 조사하고, 이번 쓰기로 인한 것으로 귀인하지 않습니다. |