콘텐츠로 이동

통합 카탈로그 엔터티 내보내기



GET /api/v1/unified_catalog/entity/export

개요

단일 엔터티 유형의 필터링 결과를 CSV로 동기 내보냅니다.

호출 전 및 사용 단계

대상 유형의 viewDefine.layout을 읽어 열과 현지화된 제목을 결정하며, 사용 가능한 레이아웃이 없으면 URN/이름/유형으로 대체합니다. 객체/배열 값은 JSON 텍스트로 CSV 셀에 기록하고, 빈 값은 빈 셀로 두며, 결과가 비어 있어도 헤더는 포함됩니다. 비동기 다운로드 작업이나 JSON 래핑 응답이 아닙니다.

현재 구현은 첫 페이지만 요청합니다. 내보내기에서 pageSize=10000으로 설정하더라도 어댑터 계층이 실제로는 500으로 제한합니다. 따라서 해당 쿼리의 처음 500개 엔터티만 내보내며 전체 데이터를 보장하지 않습니다. 더 많은 데이터는 엔터티 목록을 페이지 단위로 조회하여 직접 내보내야 하며, CSV 행 수로 전체 수량을 추론해서는 안 됩니다. filters는 GET Query에서 --data-urlencode로 전체 JSON 텍스트를 전달합니다.

모든 엔터티 유형은 백그라운드 이력 정리 진행 상황에 의존하지 않고 유효한 헬스 구성에 따라 처리됩니다. 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를 가져옵니다.

Query 요청 파라미터

파라미터명 타입 필수 설명
filters.속성 필드명 array 또는 JSON 동적 키이며, 스칼라 후보 값 배열을 권장합니다. 임의의 DQL 식을 필드명으로 사용할 수 없습니다. urn/provider/entityType 및 healthStatus와 같은 최상위 내장 필드와 snake_case 별칭은 최상위에 유지됩니다. attributes/sourceMetadata/telemetrySelectors 객체 내부 키는 평탄화됩니다.
예: ["prod"]
가져오기 또는 입력 방법: 현재 엔터티 attributes의 실제 필드명을 사용합니다. 복잡한 값 필터링의 의미는 저장된 필드 타입과 쿼리 서비스 기능을 기준으로 합니다.
filters.속성 필드명[*] JSON 동일 필드의 후보 값 1개입니다. 숫자/부울은 원래 JSON 타입을 유지하며, null과 문자열 null을 혼동해서는 안 됩니다.
예: prod
가져오기 또는 입력 방법: 현재 필드의 후보 값/기존 엔터티 값에서 가져옵니다.
entityType string Y 목록/통계에서는 선택 사항입니다. 최상위 헬스 필드로 필터링, 통계 또는 정렬할 때는 필수입니다. 생성/수정 시 필수이며 공백 제거 후 비어 있지 않아야 하고, 내보내기 시에도 필수입니다.
null 허용: False
예: database
가져오기 또는 입력 방법: 엔터티 유형 목록의 items[].entityType에서 코드를 가져오며, 유형 UUID/표시 이름이 아닙니다.
filters json 선택적 객체이며, {}는 추가 필터가 없습니다. 원시 속성 키 env는 attributes.env로 변환되고, 명시적 attributes.entityType은 최상위 entityType으로 처리되지 않습니다. 동일 필드의 여러 후보 값은 배열에 넣고, 서로 다른 필드는 쿼리 서비스가 조합하도록 합니다. 헬스 필드에는 별도의 유효한 비활성화 상태가 있으며, 사용법에서 확인할 수 있습니다.
null 허용: False
예: {"env": ["prod"]}
가져오기 또는 입력 방법: 필드명은 유형 DataSchema/속성 또는 토폴로지 필드 목록에서 가져오고, 값은 필드 통계/기존 엔터티에서 가져옵니다.
order string 선택 사항이며 기본값은 desc입니다. asc/desc만 전달할 것을 권장합니다. 공개 선언에 열거형이 추가되지 않았으므로, 임의 문자열을 저장했다고 해서 다른 방향이 지원된다고 간주해서는 안 됩니다.
null 허용: False
예: desc
가져오기 또는 입력 방법: 호출자가 asc 또는 desc를 선택합니다.
orderBy string 선택 사항이며, 기본 정렬은 쿼리 서비스가 updatedAt을 기준으로 처리합니다. 헬스 정렬에는 entityType이 필요합니다. 유형에서 헬스를 비활성화한 경우 헬스 정렬은 updatedAt desc로 대체되며, 과거 헬스 값으로 정렬하지 않습니다.
null 허용: False
예: updatedAt
가져오기 또는 입력 방법: 유형 뷰/필드 인터페이스에서 정렬 가능한 필드를 선택하며, 내장 필드는 updatedAt/name/healthScore 등이고 속성은 attributes.env를 사용합니다.
provider string 선택 사항이며, 전달하지 않으면 소스로 필터링하지 않습니다. 여러 소스는 providers를 사용하며, providers의 비어 있지 않은 값이 provider보다 우선합니다. 엔터티 소스는 수정되지 않습니다.
null 허용: False
예: manual
가져오기 또는 입력 방법: 기존 엔터티의 provider 또는 필드 값 통계의 provider 버킷에서 가져오며, 구체적인 값은 수집/보고 소스에 따라 결정됩니다.
search string 선택 사항이며, 생략하거나 빈 문자열이면 퍼지 검색을 수행하지 않습니다. 엔터티 집합에 적용되며 fieldValue의 후보 값 필터링과 동일하지 않습니다.
null 허용: False
예: demo
가져오기 또는 입력 방법: 호출자가 엔터티 이름/URN/표시 이름에서 검색어를 입력합니다.

파라미터 추가 설명

요청 파라미터 설명

파라미터명 type 필수 설명
entityType string 예 엔터티 유형 코드이며, 유형마다 내보내기 열이 다릅니다.
provider string 아니요 단일 소스 유형입니다.
search string 아니요 퍼지 검색이며 urn / display_name / name과 일치합니다.
filters json 아니요 attributes 필드 필터링입니다.
orderBy string 아니요 정렬 필드이며 기본값은 updatedAt입니다.
order string 아니요 정렬 방향이며 기본값은 desc입니다.

호출 시 유의 사항

  • 내보내기 열은 엔터티 유형 뷰 정의 viewDefine.layout을 기준으로 합니다.
  • filters는 JSON 객체 또는 문자열화된 JSON을 지원합니다.
  • 인터페이스가 성공하면 CSV 파일 스트림을 직접 반환하므로, 호출자는 파일 다운로드 방식으로 처리할 것을 권장합니다.

요청 예시

curl --get 'https://openapi.guance.com/api/v1/unified_catalog/entity/export' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode entityType=database \
  --data-urlencode 'filters={
  "env": [
    "prod"
  ]
}' \
  --data-urlencode orderBy=updatedAt \
  --data-urlencode order=desc

응답

HTTP 200, text/csv;charset=utf-8; Content-Disposition은 attachment이고 파일명은 entities_YYYYmmddHHMMSS.csv입니다. 열은 유형 뷰에 의해 결정되며, 예시는 레이아웃이 없을 때의 대체 열입니다.

필드 타입 설명
CSV.헤더 string viewDefine.layout 및 언어에 따라 생성되며, 레이아웃이 없으면 URN/이름/유형으로 대체됩니다.
CSV.행 string 각 행에는 엔터티 하나가 포함되며 최대 처음 500개 항목입니다. 쉼표/따옴표 등이 포함된 경우 CSV 이스케이프 규칙을 따릅니다.
응답 헤더 타입 설명
Content-Type string text/csv;charset=utf-8.
Content-Disposition string attachment; filename=entities_YYYYmmddHHMMSS.csv.
URN,이름,유형
urn:database:default:demo,demo,database

오류 응답

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

다운스트림 오류는 Kodo 공유 매핑을 따르며, 4xx는 실제 HTTP 상태와 ft.KodoCommonApiErr 또는 매핑된 비즈니스 코드를 반환할 수 있습니다. 모든 실패가 406으로 변환되는 것은 아닙니다. 전달되지 않은 5xx/연결 예외/성공 결과 구조 불일치는 최종적으로 500 ft.InternalServerError가 됩니다. errorCode/message/traceId를 보존하고 읽기 또는 쓰기 단계에 따라 처리해야 합니다. 성공 HTTP 응답이 엔터티의 실제 가시성 검증을 대체할 수는 없습니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방식
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드명, 타입 및 값을 확인해야 합니다.
406 ft.InvalidParameter entityType이 비어 있거나 헬스 쿼리 파라미터가 불완전함 파라미터 {}가 유효하지 않음 유형 코드를 입력하고 필드 규칙에 따라 헬스 쿼리 제약 조건을 보완해야 합니다.
500 ft.InternalServerError 다운스트림 쿼리 실패/시간 초과, 성공 데이터 형태 이상 또는 태그/팀/시간 포맷 실패 내부 오류 쿼리 범위를 줄인 후 적절히 재시도해야 합니다. 지속적으로 실패하면 traceId와 필터 조건을 보존하여 조사해야 하며, 이번 쓰기 작업으로 인한 것으로 귀인해서는 안 됩니다.

문서 평가

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