콘텐츠로 이동

통합 카탈로그 엔터티 목록



POST /api/v1/unified_catalog/entity/list

개요

유형, 소스, 속성 및 유효 헬스 상태를 기준으로 현재 워크스페이스 엔터티를 페이지 단위로 읽습니다.

호출 전 및 사용 단계

먼저 엔터티 유형 목록에서 코드를 가져오고, 다음으로 필드 통계에서 유효한 후보 값을 가져온 뒤 필요에 따라 filters를 채웁니다. 필터와 정렬을 고정한 상태로 페이지를 순회하는 것을 권장하며, items가 비어 있으면 해당 페이지에 결과가 없음을 의미합니다. 이 페이지에서는 Front 전용 인시던트 수 또는 하위 엔터티 수를 반환하지 않습니다. providers가 비어 있지 않으면 provider보다 우선합니다.

모든 엔터티 유형은 유효 헬스 구성에 따라 처리되며 백그라운드 기존 정리 진행 상황에 의존하지 않습니다. 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
가져오기 또는 입력 방법: 현재 필드 후보 값/기존 엔터티 값에서 가져옵니다.
entityType string 목록/통계에서는 선택 사항입니다. 최상위 헬스 필드로 필터링, 통계 또는 정렬할 때는 비즈니스상 필수입니다. 생성/수정 시 필수이며 공백 제거 후 비어 있지 않아야 합니다. 내보내기 시 필수입니다.
null 허용: False
예시: database
가져오기 또는 입력 방법: 엔터티 유형 목록 items[].entityType에서 코드를 가져오며, 유형 UUID/표시 이름이 아닙니다.
filters json 선택적 객체이며, {}는 추가 필터가 없습니다. 원시 속성 키 env는 attributes.env로 변환되고, 명시적 attributes.entityType은 최상위 entityType으로 처리되지 않습니다. 동일 필드의 여러 후보 값은 배열에 넣습니다. 서로 다른 필드는 쿼리 서비스가 조합합니다. 헬스 필드에는 별도의 유효 비활성 상태가 있으며 사용법을 참조하십시오.
null 허용: False
예시: {"env": ["prod"]}
가져오기 또는 입력 방법: 필드명은 유형 DataSchema/속성 또는 토폴로지 필드 목록에서 가져오고, 값은 필드 통계/기존 엔터티에서 가져옵니다.
order string 선택 사항이며 기본값은 desc입니다. asc/desc만 전달하는 것을 권장합니다. 공개 선언에 enum이 추가되지 않았으므로 임의 문자열 저장을 다른 방향 지원으로 간주해서는 안 됩니다.
null 허용: False
예시: desc
가져오기 또는 입력 방법: 호출자가 asc 또는 desc를 선택합니다.
orderBy string 선택 사항이며, 기본 정렬은 쿼리 서비스가 updatedAt 기준으로 처리합니다. 헬스 정렬에는 entityType이 필요합니다. 유형에서 헬스를 비활성화한 경우 헬스 정렬은 기존 헬스 값이 아니라 updatedAt desc로 변경됩니다.
null 허용: False
예시: updatedAt
가져오기 또는 입력 방법: 유형 뷰/필드 인터페이스에서 정렬 가능한 필드를 선택합니다. 내장 필드는 updatedAt/name/healthScore 등이며, 속성은 attributes.env를 사용합니다.
pageIndex integer 선택 사항이며 기본값 1, 공개 목록 1..10000입니다. 요청 시 한 페이지만 가져오며 자동으로 전체를 수집하지 않습니다.
null 허용: False
$maxValue: 10000
$minValue: 1
예시: 1
가져오기 또는 입력 방법: 호출자가 1부터 페이지 단위로 순회합니다.
pageSize integer 선택 사항이며 기본값 20, 공개 목록 1..200입니다. 내보내기에는 별도의 실제 상한이 있으므로 이 파라미터로 내보내기를 제어하지 않습니다.
null 허용: False
$maxValue: 200
$minValue: 1
예시: 20
가져오기 또는 입력 방법: 호출자가 표시/순회 필요에 따라 설정합니다.
provider string 선택 사항이며, 전달하지 않으면 소스로 필터링하지 않습니다. 여러 소스는 providers를 사용하며, 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 필수 설명
pageIndex integer 아니요 페이지 번호, 기본값 1
pageSize integer 아니요 페이지당 개수, 기본값 20, 최대 200
urn string 아니요 엔터티 URN으로 정확 필터링
entityType string 아니요 엔터티 유형 코드이며, 헬스 필드 필터링 또는 정렬 시 필수
provider string 아니요 단일 소스 유형
providers array[string] 아니요 여러 소스 유형 목록
search string 아니요 퍼지 검색, urn, name, display_name과 일치
filters json 아니요 attributes 필드 필터링이며 최상위 헬스 필드도 지원합니다. 헬스 필터링 시 반드시 entityType도 전달해야 합니다
orderBy string 아니요 정렬 필드, 기본값 updatedAt이며, 헬스 필드 정렬 시 반드시 entityType도 전달해야 합니다
order string 아니요 정렬 방향, asc / desc 지원, 기본값 desc

filters 사용 설명

  • 일반 key는 엔터티 attributes와 일치합니다. healthStatus/healthScore/healthUpdateAt/brokenComponents 및 snake_case 별칭은 엔터티 최상위 유효 헬스 필드와 일치합니다.
  • 예: {"env":["prod"],"project":["demo"]}; 헬스 필터 예: {"healthStatus":["warning"]}.
  • 특정 속성에 여러 값을 일치해야 하는 경우 모두 배열에 담아 전달하십시오.

호출 시 유의사항

  • 페이지네이션 인터페이스이므로 항상 pageIndex와 pageSize를 명시적으로 전달하는 것을 권장합니다.
  • provider와 providers는 둘 중 하나만 사용하는 것을 권장하며, 여러 소스 값에는 providers를 우선 사용합니다.
  • 반환 결과의 pagination.totalCount는 현재 필터 조건에 일치하는 엔터티 총수입니다.
  • 각 엔터티는 healthConfig/healthEnabled/healthScore/healthStatus/healthUpdateAt를 고정적으로 반환합니다. 모든 유형은 항상 유효 구성에 따라 반환되며 백그라운드 readiness 정리 진행 상황에 의존하지 않습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"pageIndex":1,"pageSize":20,"entityType":"database","filters":{"env":["prod"]},"orderBy":"updatedAt","order":"desc"}'

응답

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

필드 유형 설명
content object items, pagination 및 공통 declaration 컨테이너입니다.
content.items array<object> 현재 페이지 엔터티입니다.
content.items[].id integer 또는 string 또는 null 기반 엔터티 레코드 식별자이며 값이 없을 수 있습니다. 고객은 위치 확인 시 urn을 사용합니다.
content.items[].workspaceUUID string 인증 워크스페이스 UUID입니다.
content.items[].urn string 엔터티 표준 URN이며, 이후 읽기/수정/삭제에 사용합니다.
content.items[].entityType string 엔터티 유형 코드입니다.
content.items[].provider string 수집/수동 등 실제 소스이며, 값은 엔터티 보고에 의해 결정됩니다.
content.items[].name string 엔터티 이름입니다.
content.items[].displayName string 엔터티 표시 이름이며 null일 수 있습니다.
content.items[].attributes object 엔터티 동적 속성입니다. 목록에서는 쿼리 서비스가 프로젝션하며, 상세 조회에서는 사용 가능한 전체 속성을 읽습니다.
content.items[].attributes.필드명 JSON 해당 유형 DataSchema 및 보고된 실제 필드입니다. 예: env/project/owner/custom_tags/관계 구성/헬스 오버라이드 필드이며, 모든 엔터티에 반드시 존재하는 것은 아닙니다.
content.items[].telemetrySelectors array 또는 object 기존 텔레메트리 연결 JSON이며, 기저 null 값이 {}로 정규화될 수 있어 항상 배열임을 보장하지 않습니다.
content.items[].telemetrySelectors[] JSON 각 텔레메트리 연결 동적 항목이며 원래 구성대로 유지됩니다. 쿼리 결과가 아닙니다.
content.items[].sourceMetadata object 소스 원시 메타데이터이며 목록에서는 빈 객체일 수 있습니다. 상세 조회에서 이 데이터를 명시적으로 요청하며, 구체적인 키는 소스에 따릅니다.
content.items[].sourceMetadata.필드명 JSON 소스 시스템 사용자 정의 메타 정보이며, 범용 필수 프로토콜로 간주해서는 안 됩니다.
content.items[].healthScore integer 또는 null 유효 헬스 점수이며, 음수/값 없음은 null로 정규화됩니다. 헬스 비활성화 시 null이며 0과 직접 같지 않습니다.
content.items[].healthStatus string healthy/warning/critical/unknown; 헬스 비활성화 시 unknown입니다.
content.items[].healthUpdateAt string 또는 null 헬스 업데이트 시간이며 일반적으로 YYYY-MM-DD HH:mm:ss입니다. 비활성화/값 없음은 null입니다.
content.items[].createdAt string 또는 null 생성 시간이며 일반적으로 YYYY-MM-DD HH:mm:ss이고 서비스 형식에 따라 반환됩니다.
content.items[].updatedAt string 또는 null 최종 업데이트 시간이며 생성 시간과 동일한 형식입니다.
content.items[].healthConfig object 엔터티 오버라이드 정책이며 유형 정책의 복사본이 아닙니다.
content.items[].healthConfig.mode string inherit/func/disabled; 기존 func_id만 func로 정규화됩니다.
content.items[].healthConfig.funcId string func 모드에서만 나타나는 함수 UUID입니다.
content.items[].healthEnabled boolean 유형과 엔터티 구성을 종합한 유효 스위치입니다. 유형이 disabled이면 엔터티 custom도 활성화할 수 없습니다.
content.items[].entityStatus string online/offline, 기존 데이터 기본값은 online입니다. 상태는 헬스 등급과 같지 않습니다.
content.items[].lifecycleManaged boolean 엔터티 수명 주기 관리 대상인지 여부입니다. 기본값 false입니다.
content.items[].lastReportedAt integer 또는 null 최근 보고 Unix 초이며 값이 없으면 null입니다.
content.items[].offlineAt integer 또는 null 오프라인 Unix 초이며 오프라인이 아니면 null입니다.
content.items[].deleteAt integer 또는 null 예상 수명 주기 정리 Unix 초이며 예약되지 않았으면 null입니다. 이번 API 삭제 시간이 아닙니다.
content.items[].statusUpdatedAt integer 또는 null 엔터티 상태 업데이트 시간 Unix 초이며 값이 없으면 null입니다.
content.items[].teamInfo array<object> owner를 기준으로 조회한 팀 요약입니다. 기존 참조를 찾을 수 없으면 가짜 팀을 구성하지 않습니다.
content.items[].teamInfo[].uuid string 팀 group_ UUID입니다.
content.items[].teamInfo[].type string 일반적으로 team입니다.
content.items[].teamInfo[].name string 현재 팀 이름입니다.
content.items[].teamInfo[].members array 팀 구성원 원본 JSON입니다. 구체적인 구성원 필드는 팀 관리 규약을 따르며, 이 페이지에서 추가로 전체 구성원 상세를 조회하지 않습니다.
content.items[].teamInfo[].members[] JSON 팀에 저장된 구성원 요소이며 계정 식별자/객체일 수 있고, 팀 상세를 기준으로 합니다.
content.items[].tagsInfo array<object> 현재 공간에 존재하는 태그 요약이며, 확인되지 않으면 []입니다.
content.items[].tagsInfo[].name string 태그 이름입니다.
content.items[].tagsInfo[].uuid string 태그 UUID입니다.
content.items[].tagsInfo[].colour string 색상이며 값이 없으면 빈 문자열입니다.
content.items[].tagsInfo[].scope array<string> 유효 범위 배열입니다. 누락된 기존 값은 [all]로 정규화되며, all은 다른 범위와 함께 사용할 수 없습니다.
content.items[].tagsInfo[].scope[] string all/scene/monitor/dialing/security/infrastructure/catalog; 태그의 현재 구성에 따라 반환됩니다.
content.pagination object 페이지네이션 정보이며 content에 유지되고 pageInfo로 승격된 구조가 아닙니다.
content.pagination.pageIndex integer 현재 페이지이며 1부터 시작합니다.
content.pagination.pageSize integer 실제 페이지 크기입니다.
content.pagination.count integer 이 페이지의 항목 수입니다.
content.pagination.totalCount integer 현재 필터 조건의 엔터티 총수이며, 전체 워크스페이스의 무조건 총수가 아닙니다.
content.declaration object 공통 선언이며 items 요소마다 개별 삽입되지 않습니다.
{
  "code": 200,
  "content": {
    "items": [
      {
        "id": null,
        "workspaceUUID": "wksp_example",
        "urn": "urn:database:default:demo",
        "entityType": "database",
        "provider": "manual",
        "name": "demo",
        "displayName": "Demo database",
        "attributes": {
          "env": "prod",
          "project": "demo"
        },
        "telemetrySelectors": {},
        "sourceMetadata": {},
        "healthScore": null,
        "healthStatus": "unknown",
        "healthUpdateAt": null,
        "createdAt": "2026-11-18 10:00:00",
        "updatedAt": "2026-11-18 10:00:00",
        "healthConfig": {
          "mode": "inherit"
        },
        "healthEnabled": false,
        "entityStatus": "online",
        "lifecycleManaged": false,
        "lastReportedAt": null,
        "offlineAt": null,
        "deleteAt": null,
        "statusUpdatedAt": null,
        "teamInfo": [],
        "tagsInfo": []
      }
    ],
    "pagination": {
      "pageIndex": 1,
      "pageSize": 20,
      "count": 1,
      "totalCount": 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 헬스 필터링/정렬을 사용하지만 entityType 누락 파라미터 {} 무효 대상 엔터티 유형 코드를 명확히 입력합니다. 속성에 동일한 이름의 필드가 있으면 attributes. 접두사를 사용하여 구분합니다.
500 ft.InternalServerError 다운스트림 쿼리 실패/시간 초과, 성공 데이터 형상 이상 또는 태그/팀/시간 형식 지정 실패 내부 오류 쿼리 범위를 좁힌 후 적절히 재시도합니다. 지속 실패 시 traceId와 필터 조건을 보존하여 조사하며, 이번 쓰기로 인한 것으로 귀인하지 않습니다.
406 ft.ParameterValidationFailed 저장된 태그 scope가 유효하지 않으며 태그 요약을 읽을 때 검증 실패 invalid scope message=invalid scope일 때 관리자가 관련 태그의 기존 범위(all 또는 유효한 범위 배열)를 수정합니다. 엔터티 쿼리 파라미터를 반복해서 수정하는 것이 아닙니다.

문서 평가

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