콘텐츠로 이동

통합 카탈로그 엔터티 필드 값 개수 통계



POST /api/v1/unified_catalog/entity/field_value/count

개요

필드별로 현재 일치하는 엔터티의 후보 값과 개수를 집계합니다.

호출 전 및 사용 단계

fieldList는 표준 필드 식별자를 기준으로 중복을 제거하고 첫 번째 명시적 표기 방식을 유지합니다. env는 attributes.env와 동일하며, attributes.entityType는 최상위 entityType와 다릅니다. search는 먼저 엔터티 집합을 제한하고, fieldValue는 그다음 후보 버킷만 좁힙니다. totalCount는 버킷 개수가 아니라 엔터티 총개수이며, 배열 필드는 값을 분해한 뒤 각 버킷 개수의 합이 엔터티 개수와 다를 수 있습니다.

모든 엔터티 유형은 유효한 헬스 설정에 따라 처리되며, 백그라운드의 이력 정리 진행 상황에 의존하지 않습니다. 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 요청 파라미터

파라미터명 유형 필수 설명
providers[*] string 배열 내 하나의 소스입니다. 상위 배열을 생략하면 필터링하지 않습니다.
예: manual
가져오기 또는 입력 방법: 기존 엔터티의 단일 provider 값입니다.
filters.속성 필드명 array 또는 JSON 동적 키로, 스칼라 후보 값 배열을 권장합니다. 임의의 DQL 표현식을 필드명으로 사용할 수 없습니다. urn/provider/entityType 및 healthStatus와 snake_case 별칭 같은 최상위 내장 필드는 최상위에 유지되며, attributes/sourceMetadata/telemetrySelectors 객체 내부 키는 평탄화됩니다.
예: ["prod"]
가져오기 또는 입력 방법: 현재 엔터티 attributes의 실제 필드명을 사용합니다. 복잡한 값 필터링의 의미는 저장된 필드 유형과 쿼리 서비스 기능에 따릅니다.
filters.속성 필드명[*] JSON 동일 필드의 후보 값 하나입니다. 숫자/불리언은 원래 JSON 유형을 유지하고, null과 문자열 null을 혼동하지 마세요.
예: prod
가져오기 또는 입력 방법: 현재 필드의 후보 값 또는 기존 엔터티 값에서 가져옵니다.
fieldList[*] string 배열 속성은 여러 후보 버킷으로 분해됩니다. 헬스 필드가 포함되면 entityType을 반드시 전달해야 합니다. DQL이 아니라 쿼리 서비스가 인식할 수 있는 필드를 사용합니다.
예: attributes.env
가져오기 또는 입력 방법: 단일 최상위/속성 필드명입니다.
entityType string 목록/집계에서는 선택 사항입니다. 최상위 헬스 필드를 필터링, 집계 또는 정렬할 때는 업무상 필수입니다. 생성/수정 시 필수이며 공백 제거 후 비어 있지 않아야 합니다. 내보내기 시 필수입니다.
null 허용: False
예: database
가져오기 또는 입력 방법: 엔터티 유형 목록의 items[].entityType에서 코드를 가져옵니다. 유형 UUID/표시 이름이 아닙니다.
fieldList array Y 필수 1~64개 항목입니다. 공백 항목은 건너뛰고, 동일한 표준 필드 별칭은 중복 제거합니다. 유효한 항목이 없으면 406을 반환합니다. 접두사 없는 env와 attributes.env는 동일한 필드이며, attributes.entityType는 최상위 entityType와 다릅니다.
null 허용: False
최대 길이: 64
최소 길이: 1
예: ["provider", "attributes.env"]
가져오기 또는 입력 방법: 토폴로지 필드 목록/기존 유형 속성에서 집계할 필드를 가져옵니다.
fieldValue string 선택 사항이며, 공백 제거 후 비어 있지 않은 경우에만 다운스트림으로 전달합니다. 버킷만 필터링하며 search가 엔터티 집합에 적용되는 효과를 변경하지 않습니다. totalCount는 여전히 엔터티 일치 총량이며 후보 키워드에 따라 줄어들지 않습니다.
null 허용: False
예: prod
가져오기 또는 입력 방법: 사용자가 좁히려는 필드 후보 값 키워드를 입력합니다.
filters json 선택적 객체이며 {}는 추가 필터가 없습니다. 접두사 없는 속성 키 env는 attributes.env로 변환되며, 명시적 attributes.entityType는 최상위 entityType로 처리되지 않습니다. 동일 필드의 여러 후보 값은 배열에 넣고, 서로 다른 필드는 쿼리 서비스가 조합하도록 합니다. 헬스 필드에는 별도의 유효한 비활성 상태가 있으며 사용법을 참조하세요.
null 허용: False
예: {"env": ["prod"]}
가져오기 또는 입력 방법: 필드명은 유형 DataSchema/속성 또는 토폴로지 필드 목록에서 가져오고, 값은 필드 통계/기존 엔터티에서 가져옵니다.
provider string 선택 사항이며, 전달하지 않으면 소스로 필터링하지 않습니다. 여러 소스는 providers를 사용하며, 해당 비어 있지 않은 값이 provider보다 우선합니다. 엔터티 소스는 수정하지 않습니다.
null 허용: False
예: manual
가져오기 또는 입력 방법: 기존 엔터티 provider 또는 필드 값 집계의 provider 버킷에서 가져옵니다. 구체적인 값은 수집/보고 소스에 따라 결정됩니다.
providers array 선택적 소스 배열로, 비어 있지 않으면 provider보다 우선합니다. []는 소스 필터를 추가하지 않으며, 빈 소스만 선택하는 것이 아닙니다. 공개 배열은 항목별 문자열 검증이 선언되어 있지 않으므로 실제 문자열만 사용하는 것을 권장합니다.
null 허용: False
예: ["manual"]
가져오기 또는 입력 방법: field_value/count의 provider 후보 버킷에서 실제 소스 값을 가져옵니다.
search string 선택 사항이며, 생략하거나 빈 문자열이면 퍼지 검색을 하지 않습니다. 엔터티 집합에 적용되며 fieldValue의 후보 값 필터링과 동일하지 않습니다.
null 허용: False
예: demo
가져오기 또는 입력 방법: 호출자가 엔터티 이름/URN/표시 이름에서 검색어를 입력합니다.
urn string 읽기/삭제 시 필수이며 앞뒤 공백 제거 후 비어 있지 않아야 합니다. 목록/집계에서는 선택적 정확 필터입니다. 수정 시에는 원래 URN을 명확히 입력하여 이름 변경 시 다른 엔터티가 생성되는 것을 방지하는 것이 좋습니다.
null 허용: False
예: urn:database:default:demo
가져오기 또는 입력 방법: 현재 워크스페이스 엔터티 목록의 items[].urn에서 가져오며, 가능하면 전체 URN을 그대로 사용합니다.

파라미터 추가 설명

요청 파라미터 설명

파라미터명 type 필수 설명
fieldList array[string] 예 집계할 필드 목록이며 최대 64개 항목입니다.
urn string 아니요 엔터티 URN으로 정확 필터링합니다.
entityType string 아니요 엔터티 유형 필터입니다.
provider string 아니요 단일 소스 유형입니다.
providers array[string] 아니요 여러 소스 유형 목록입니다.
search string 아니요 퍼지 검색 조건입니다.
fieldValue string 아니요 후보 버킷만 필터링합니다. search와 함께 사용할 수 있으며, 두 파라미터는 각각 전체 엔터티 집합과 후보 값에 적용됩니다.
filters json 아니요 attributes 필드 필터입니다.

fieldList 필드 설명

  • 엔터티 기본 필드를 지원합니다. 예: entityType, provider, urn, name, displayName.
  • attributes 필드를 지원합니다. 예: env, project, attributes.env, attributes.project.
  • env는 attributes.env와 동일합니다.

호출 시 주의 사항

  • 응답의 totalCount는 현재 필터 조건에 일치한 엔터티 총개수를 나타내며 fieldList의 영향을 받지 않습니다.
  • 배열 유형 속성은 여러 값으로 분해되어 각각 집계됩니다.
  • fieldList 또는 filters에 헬스 필드가 포함되면 entityType을 반드시 전달해야 합니다. 유형이 disabled이면 unknown/null의 유효한 비활성 상태로 집계하며, 과거 헬스 값을 읽지 않습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/field_value/count' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"entityType":"database","fieldList":["provider","attributes.env"],"search":"demo","fieldValue":"","filters":{}}'

응답

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

필드 유형 설명
content.totalCount integer 일치하는 엔터티 총개수이며 후보 값 키워드의 영향을 받지 않습니다.
content.items array<object> 중복 제거된 각 필드의 집계 항목입니다.
content.items[].field string 요청에서 첫 번째로 유지된 필드 표기입니다.
content.items[].values array<object> 후보 값 버킷이며, 일치 항목이 없으면 []입니다.
content.items[].values[].value JSON 필드의 실제 값이며 null일 수 있습니다. 비활성화된 헬스 필드는 유효 값 기준으로 집계합니다.
content.items[].values[].count integer 해당 값과 일치한 엔터티 수이며 음수가 아닙니다.
content.declaration object 공통 선언입니다.
{
  "code": 200,
  "content": {
    "totalCount": 1,
    "items": [
      {
        "field": "provider",
        "values": [
          {
            "value": "manual",
            "count": 1
          }
        ]
      },
      {
        "field": "attributes.env",
        "values": [
          {
            "value": "prod",
            "count": 1
          }
        ]
      }
    ],
    "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 유효한 fieldList가 없거나 헬스 집계/필터링에 entityType이 누락됨 파라미터 {}가 유효하지 않음 1~64개의 유효한 필드와 대상 유형을 제출하세요. 빈 문자열만 입력하지 마세요.
500 ft.InternalServerError 다운스트림 쿼리 실패/시간 초과, 성공 데이터 형태 이상 또는 태그/팀/시간 형식 지정 실패 내부 오류 쿼리 범위를 좁힌 후 적절히 재시도하세요. 계속 실패하면 traceId와 필터 조건을 보존하여 조사하고, 이번 쓰기로 인한 것으로 단정하지 마세요.

문서 평가

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