콘텐츠로 이동

통합 카탈로그 엔터티 유형 목록



POST /api/v1/unified_catalog/entity_type_cfg/list

개요

현재 워크스페이스에서 표시되는 엔터티 유형 및 해당 재정의 구성을 페이지 단위로 조회합니다.

호출 전 및 사용 단계

목록에는 표시되는 공식 유형과 현재 워크스페이스의 사용자 지정 유형이 포함되며, withDefault=false인 경우 후자만 포함됩니다. 숨겨진 시스템 유형/default 생성 템플릿은 일반 목록에 포함되지 않습니다. 기본 유형이 우선하며, 시스템 유형은 표시 가중치 내림차순, 그다음 생성 시간/번호 오름차순으로 정렬됩니다.

OpenAPI 기본값은 withEntityCount=true이며, 이 경우 엔터티 조회 서비스에 액세스합니다. false이면 수량을 생략합니다. filters는 카운트만 제한하며 일치 항목이 없는 유형을 제거하지 않습니다. summaryOnly=true이면 기본 Schema/View를 생략하지만 customProperties 등 재정의 값을 포함할 수 있습니다. 이 공개 엔드포인트는 Front의 유효한 health form/effectiveViewDefine/entityStatusConfig를 반환하지 않습니다. 모든 유형의 health 기능은 항상 읽을 수 있으며, system은 기본값이 default, 그 외는 기본값이 disabled입니다.

요청 헤더

파라미터명 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 파라미터

파라미터명 유형 필수 설명
filters.속성 필드명 JSON 동적 키와 값은 엔터티 조회 서비스에서 해석합니다. 빈 객체는 카운트를 필터링하지 않으며, 스칼라 후보 값 배열을 권장합니다.
예시: ["prod"]
가져오기 또는 입력 방법: 기존 엔터티 속성 필드명과 후보 값입니다.
filters json 선택적 객체입니다. 현재는 withEntityCount=true일 때만 엔터티 수량 집계에 사용되며, 카운트가 0인 유형을 제거하지 않고, 이를 근거로 일치하는 엔터티가 있는 유형만 반환됨을 보장하지 않습니다. withEntityCount=false일 때는 이 필터 카운트를 실행하지 않습니다.
null 허용: False
예시: {"env": ["prod"]}
가져오기 또는 입력 방법: 엔터티 attributes 필드와 값을 선택하며, 해당 유형 Schema 및 엔터티 필드 통계에서 가져옵니다.
pageIndex integer 선택 사항이며 기본값은 1이고 최소값은 1이며, 컨트롤러 최대값은 100000입니다.
null 허용: False
$minValue: 1
예시: 1
가져오기 또는 입력 방법: 호출자가 1부터 유형 구성 목록을 순회합니다.
pageSize integer 선택 사항이며 기본값은 20이고 1..200입니다.
null 허용: False
$maxValue: 200
$minValue: 1
예시: 20
가져오기 또는 입력 방법: 클라이언트 표시 또는 일괄 읽기 요구에 따라 설정합니다.
search string 선택 사항이며 앞뒤 공백을 제거합니다. entityType/name과 일치하며 description/임의 속성 값은 검색하지 않습니다.
null 허용: False
예시: demo
가져오기 또는 입력 방법: 유형 코드/표시 이름 키워드를 입력합니다.
summaryOnly boolean 선택 사항이며 기본값은 false입니다. true이면 schemaDefine/viewDefine/fieldMetadata를 읽거나 반환하지 않지만 extraConfig/healthConfig/customProperties 및 선택적 카운트는 계속 반환하며, YAML 필드가 전혀 없음을 보장하지 않습니다.
null 허용: False
예시: true
가져오기 또는 입력 방법: 카탈로그 선택기에서 true로 경량 유형 요약을 가져올 수 있습니다.
withDefault boolean 선택 사항이며 기본값은 true입니다. false이면 현재 워크스페이스의 사용자 지정 유형만 가져오며, status=3인 default 생성 템플릿은 반환하지 않습니다.
null 허용: False
예시: true
가져오기 또는 입력 방법: 현재 표시되는 공식 기본 유형을 포함할지 여부입니다.
withEntityCount boolean OpenAPI 기본값은 true입니다. false이면 entityCount를 생략하고 다운스트림 쿼리를 줄입니다. Front/AIAPI의 기본값 false를 적용하지 마십시오.
null 허용: False
예시: true
가져오기 또는 입력 방법: 각 유형에 대해 엔터티 수량을 조회해야 하는지 여부입니다.

파라미터 추가 설명

요청 파라미터 설명

파라미터명 type 필수 설명
pageIndex integer 아니요 페이지 번호, 기본값 1
pageSize integer 아니요 페이지당 수량, 기본값 20
search string 아니요 엔터티 유형 코드 또는 표시 이름으로 검색
filters json 아니요 엔터티 attributes로 필터링하여 엔터티 유형을 역으로 필터링합니다.
withDefault boolean 아니요 시스템 기본 유형 포함 여부, 기본값 true
withEntityCount boolean 아니요 엔터티 수량 반환 여부, 기본값 true
summaryOnly boolean 아니요 경량 요약 반환 여부, true이면 schema/view/effective 정의를 읽거나 반환하지 않습니다.

호출 시 유의 사항

  • 페이지네이션 API이므로 pageIndex와 pageSize를 명시적으로 전달하는 것이 좋습니다.
  • 반환 결과의 extraConfig는 현재 워크스페이스 관점의 엔터티 유형 추가 구성입니다.
  • 기본 유형과 사용자 지정 유형은 withDefault에 따라 결과에 함께 나타날 수 있습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity_type_cfg/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"pageIndex":1,"pageSize":20,"withDefault":true,"withEntityCount":false,"summaryOnly":true}'

응답

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

필드 유형 설명
content.items array<object> 현재 페이지의 유형입니다.
content.items[].id integer 또는 null 유형 레코드 번호입니다. 새로 생성하여 제출하기 전에는 null일 수 있습니다.
content.items[].uuid string enty_ 유형 UUID입니다. 생성 템플릿은 default입니다.
content.items[].workspaceUUID string 유형이 속한 워크스페이스입니다. 공식 유형은 비어 있을 수 있으며, 워크스페이스 재정의 구성은 여전히 현재 워크스페이스 기준으로 별도 처리됩니다.
content.items[].entityType string 안정적인 유형 코드이며 표시 이름이 아닙니다.
content.items[].name string 표시 이름입니다.
content.items[].description string 설명입니다.
content.items[].sourceType string default는 공식/기본, custom은 사용자 지정입니다.
content.items[].isSystem integer 시스템 수준 표시이며 sourceType과 단순히 동일하지 않습니다.
content.items[].isHidden integer 숨김 표시입니다. 일반 목록에서는 숨겨진 시스템 유형을 제외합니다.
content.items[].showRank integer 또는 null 시스템 유형 표시 정렬 가중치이며, 값이 없으면 null입니다.
content.items[].entityTypeGroupUUID string 레거시 그룹 식별자이며 비어 있을 수 있습니다. 공개 API는 폐기된 그룹 쓰기 파라미터를 허용하지 않습니다.
content.items[].groupInfo object 또는 null 그룹 요약입니다. 누락 시 {}일 수 있고, 기본 유형 수정 시 null일 수 있습니다.
content.items[].groupInfo.uuid string 레거시 그룹이 존재할 때의 UUID입니다.
content.items[].groupInfo.name string 레거시 그룹이 존재할 때의 이름입니다.
content.items[].schemaDefine string 원본 DataSchema YAML입니다. summaryOnly 목록에서는 생략됩니다.
content.items[].viewDefine string 원본 UIView YAML입니다. summaryOnly 목록에서는 생략됩니다.
content.items[].extend object 동적 유형 확장입니다.
content.items[].extend.확장 키 JSON 구체적인 키는 원래 유형 정의를 따릅니다.
content.items[].status integer 정상은 0, default 생성 템플릿은 3이며 목록의 활성 리소스가 아닙니다.
content.items[].creator string 생성 주체 UUID/시스템 식별자입니다.
content.items[].updator string 업데이트 주체입니다.
content.items[].createAt integer 생성 Unix 초입니다.
content.items[].updateAt integer 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1일 수 있습니다.
content.items[].deleteAt integer 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다.
content.items[].entityCount integer 현재 워크스페이스의 엔터티 수량입니다. 목록에서 withEntityCount=false이면 생략됩니다. 생성/수정 응답에서 0은 실제 수량을 조회했음을 의미하지 않습니다.
content.items[].extraConfig object 현재 워크스페이스의 추가 구성이며, 기본값은 {}입니다.
content.items[].extraConfig.telemetrySelectors array 조건부로 존재하는 텔레메트리 연관 구성이며, 엔터티 조회 결과와 동일하지 않습니다.
content.items[].extraConfig.telemetrySelectors[] JSON 해당 구성의 동적 항목입니다.
content.items[].extraConfig.disabledBuiltInViews array<string> 조건부로 존재하는 비활성화된 내장 뷰 식별자입니다.
content.items[].extraConfig.disabledBuiltInViews[] string 단일 뷰 식별자입니다.
content.items[].extraConfig.기타 키 JSON 동적 확장이며 실제 값을 유지합니다.
content.items[].healthConfig object 현재 워크스페이스 유형의 유효 health 정책입니다. 생성 응답에 이 필드가 항상 포함되는 것은 아닙니다.
content.items[].healthConfig.mode string system은 기본값이 default이고, 그 외는 구성되지 않으면 disabled입니다. 구성 후에는 func/disabled일 수 있습니다.
content.items[].healthConfig.funcId string func일 때만 존재하는 함수 UUID입니다.
content.items[].customProperties string 현재 워크스페이스의 원본 사용자 지정 필드 YAML이며 주석을 유지합니다.
content.pagination object 페이지네이션 정보이며 content에 유지되고, pageInfo로 상위에 올린 구조가 아닙니다.
content.pagination.pageIndex integer 현재 페이지이며 1부터 시작합니다.
content.pagination.pageSize integer 실제 페이지당 크기입니다.
content.pagination.count integer 이 페이지의 항목 수입니다.
content.pagination.totalCount integer 현재 표시되는 유형 구성의 총수이며 엔터티 수량이 아닙니다. 카운트 filters에 따라 일치 항목이 없는 유형을 제외하지 않습니다.
content.declaration object 외부 선언입니다.
{
  "code": 200,
  "content": {
    "items": [
      {
        "id": 100,
        "uuid": "enty_example",
        "workspaceUUID": "wksp_example",
        "entityType": "demo_service",
        "name": "示例服务",
        "description": "业务服务目录",
        "sourceType": "custom",
        "isSystem": 0,
        "isHidden": 0,
        "showRank": null,
        "entityTypeGroupUUID": "",
        "extend": {},
        "creator": "wsak_example",
        "updator": "wsak_example",
        "createAt": 1785427200,
        "updateAt": 1785427200,
        "deleteAt": -1,
        "status": 0,
        "groupInfo": {},
        "extraConfig": {},
        "healthConfig": {
          "mode": "disabled"
        },
        "customProperties": "# 保留原文与注释\ncustom_properties:\n  - name: business_owner\n    title: 业务负责人\n    type: string\n    required: false\n    extension_scope: custom\n    writable_sources: [manual, gitops]\n    capabilities: {display: true, edit: true, filter: false, sort: false}\n"
      }
    ],
    "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 파일 형식 오류 예시에 따라 객체를 제출하고 배열/문자열을 사용하지 마십시오.
500 ft.InternalServerError 유형 읽기, 엔터티 카운트, 레거시 구성/원본 Schema 구문 분석 또는 포맷팅 실패 내부 오류 traceId 및 유형/필터 조건을 유지하고 레거시 정의와 조회 서비스를 확인하십시오. 이는 읽기 실패이며 이번에 구성이 저장되었음을 의미하지 않습니다.

문서 평가

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