통합 카탈로그 엔터티 유형 목록¶
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 및 유형/필터 조건을 유지하고 레거시 정의와 조회 서비스를 확인하십시오. 이는 읽기 실패이며 이번에 구성이 저장되었음을 의미하지 않습니다. |