통합 카탈로그 엔터티 유형 상세¶
GET /api/v1/unified_catalog/entity_type_cfg/get
개요¶
단일 유형의 원본 정의, 워크스페이스 오버라이드 및 유효 DataSchema를 조회합니다.
호출 전 준비 및 사용 단계¶
entityTypeUUID와 entityType 중 최소 하나를 전달해야 합니다. 비어 있지 않은 UUID가 우선하며, 두 값이 일치하지 않아도 UUID를 기준으로 처리하고 교차 검증에는 사용하지 않습니다. entityTypeUUID=default는 숨겨진 생성 템플릿(status=3)을 조회하는 것이며 생성 동작이 아니고, 카운트는 0입니다. 일반 상세 조회는 항상 현재 워크스페이스의 엔터티 수를 조회하며, Front의 withEntityCount 파라미터로 비활성화할 수 없습니다.
원본 schemaDefine/viewDefine/customProperties와 병합된 effectiveSchemaDefine을 반환합니다. 공개 API는 Front 전용 effectiveViewDefine/헬스 보존 폼 필드/entityStatusConfig를 보완하지 않습니다. 이후 편집에는 원본 텍스트를 사용하며, effective 정의를 다시 기록할 수 없습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| entityType | string | 생성 시 필수이며, 공백을 제거한 뒤 ^[a-zA-Z][0-9a-zA-Z_-]{0,63}$와 일치해야 합니다. 첫 글자 뒤에는 숫자/영문자/_/-를 사용할 수 있고 대소문자를 구분합니다. 고유한 코드를 선택해야 하며, 최소한 현재 표시되는 공식/사용자 정의 유형과 이름이 같으면 거부됩니다. 생성 후에는 수정을 통해 코드를 변경할 수 없습니다. 상세 조회 시 UUID가 없을 때 사용하는 대체 식별자입니다.null 허용: False 예시: demo_service가져오기 또는 입력 방법: 호출자가 유형 코드를 선택하며, 조회 시에는 목록의 entityType에서 그대로 가져옵니다. |
|
| entityTypeUUID | string | 상세 조회 시 entityType과 함께 최소 하나를 전달해야 하며, UUID가 비어 있지 않으면 우선 적용되고 두 값의 일치 여부는 검증하지 않습니다. default는 숨겨진 status=3 생성 템플릿을 반환하며 엔터티 수를 조회하지 않습니다. 삭제 시에는 코드가 아닌 실제 유형 UUID가 필수입니다.null 허용: False 예시: enty_example가져오기 또는 입력 방법: 유형 목록의 items[].uuid에서 enty_ 식별자를 가져오거나, default로 생성 템플릿을 가져옵니다. |
파라미터 추가 설명¶
요청 파라미터 설명
| 파라미터명 | type | 필수 | 설명 |
|---|---|---|---|
| entityTypeUUID | string | 아니요 | 엔터티 유형 UUID |
| entityType | string | 아니요 | 엔터티 유형 코드 |
호출 시 유의 사항
entityTypeUUID와entityType중 최소 하나를 전달해야 합니다.entityTypeUUID=default이면 사용자 정의 엔터티 유형 생성 템플릿을 반환하며, 이 템플릿은status=3데이터로 엔터티 유형 목록에 나타나지 않습니다.- 두 파라미터를 모두 전달하는 경우 동일한 엔터티 유형을 가리키도록 하는 것이 좋습니다.
- 반환 결과에는
schemaDefine,viewDefine,extraConfig가 포함됩니다. - 현재 워크스페이스의
customProperties와 병합된effectiveSchemaDefine을 반환합니다. - OpenAPI 호환성 유지: 목록과 상세 조회는 기본적으로
entityCount를 조회하여 반환합니다.
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/unified_catalog/entity_type_cfg/get' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode entityTypeUUID=enty_example
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 유형 레코드 번호이며, 생성 제출 전에는 null일 수 있습니다. |
| content.uuid | string | enty_ 유형 UUID이며, 생성 템플릿은 default입니다. |
| content.workspaceUUID | string | 유형이 속한 워크스페이스이며, 공식 유형은 비어 있을 수 있고 워크스페이스 오버라이드 설정은 여전히 현재 워크스페이스 기준으로 별도 처리됩니다. |
| content.entityType | string | 안정적인 유형 코드이며 표시 이름이 아닙니다. |
| content.name | string | 표시 이름입니다. |
| content.description | string | 설명입니다. |
| content.sourceType | string | default는 공식/기본, custom은 사용자 정의입니다. |
| content.isSystem | integer | 시스템 수준 플래그이며 sourceType과 단순히 동일하지 않습니다. |
| content.isHidden | integer | 숨김 플래그이며, 일반 목록에서는 숨겨진 시스템 유형이 제외됩니다. |
| content.showRank | integer 또는 null | 시스템 유형 표시 정렬 가중치이며, 값이 없으면 null입니다. |
| content.entityTypeGroupUUID | string | 과거 그룹 식별자로 비어 있을 수 있으며, 공개 API는 폐기된 그룹 쓰기 파라미터를 허용하지 않습니다. |
| content.groupInfo | object 또는 null | 그룹 요약이며, 없으면 {}일 수 있고 기본 유형 수정 시 null일 수 있습니다. |
| content.groupInfo.uuid | string | 과거 그룹이 존재할 때의 UUID입니다. |
| content.groupInfo.name | string | 과거 그룹이 존재할 때의 이름입니다. |
| content.schemaDefine | string | 원본 DataSchema YAML이며, summaryOnly 목록에서는 생략됩니다. |
| content.viewDefine | string | 원본 UIView YAML이며, summaryOnly 목록에서는 생략됩니다. |
| content.extend | object | 동적 유형 확장입니다. |
| content.extend.확장 키 | JSON | 구체적인 키는 원래 유형 정의를 따릅니다. |
| content.status | integer | 정상은 0, default 생성 템플릿은 3이며 목록에 있는 활성 리소스가 아닙니다. |
| content.creator | string | 생성 주체 UUID/시스템 식별자입니다. |
| content.updator | string | 수정 주체입니다. |
| content.createAt | integer | 생성 Unix 초입니다. |
| content.updateAt | integer | 수정 Unix 초이며, 수정되지 않은 경우 -1일 수 있습니다. |
| content.deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content.entityCount | integer | 현재 워크스페이스의 엔터티 수이며, 목록에서 withEntityCount=false이면 생략됩니다. 생성/수정 응답의 0은 실제 수량을 조회했다는 의미가 아닙니다. |
| content.extraConfig | object | 현재 워크스페이스의 추가 설정이며, 기본값은 {}입니다. |
| content.extraConfig.telemetrySelectors | array | 조건에 따라 존재하는 텔레메트리 연관 설정이며 엔터티 조회 결과와 동일하지 않습니다. |
| content.extraConfig.telemetrySelectors[] | JSON | 해당 설정의 동적 항목입니다. |
| content.extraConfig.disabledBuiltInViews | array<string> | 조건에 따라 존재하는 비활성화된 내장 뷰 식별자입니다. |
| content.extraConfig.disabledBuiltInViews[] | string | 단일 뷰 식별자입니다. |
| content.extraConfig.기타 키 | JSON | 동적 확장이며 실제 값을 유지합니다. |
| content.healthConfig | object | 현재 워크스페이스 유형의 유효 헬스 정책이며, 생성 응답에 이 필드가 항상 포함되는 것은 아닙니다. |
| content.healthConfig.mode | string | 시스템 기본값은 default이고, 그 외 미설정은 disabled이며, 설정 후에는 func/disabled일 수 있습니다. |
| content.healthConfig.funcId | string | func일 때만 존재하는 함수 UUID입니다. |
| content.customProperties | string | 현재 워크스페이스의 원본 사용자 정의 필드 YAML이며 주석을 보존합니다. |
| content.effectiveSchemaDefine | string | base schema에 현재 워크스페이스에서 파싱된 custom_properties를 병합한 YAML이며 주석 보존은 보장되지 않습니다. 공개 상세/생성/수정에는 포함되고 목록에는 포함되지 않습니다. 다시 기록할 수 있는 원본 Schema가 아닙니다. |
| content.declaration | object | 공용 선언입니다. |
{
"code": 200,
"content": {
"id": 100,
"uuid": "enty_example",
"workspaceUUID": "wksp_example",
"entityType": "demo_service",
"name": "示例服务",
"description": "业务服务目录",
"sourceType": "custom",
"isSystem": 0,
"isHidden": 0,
"showRank": null,
"entityTypeGroupUUID": "",
"schemaDefine": "kind: DataSchema\nentity_type: demo_service\nproperties:\n - name: env\n type: string\n required: false\n",
"viewDefine": "kind: UIView\nlayout:\n - group:\n display_name: 基础信息\n fields:\n - bind: env\n title: 环境\n ui_type: input\n",
"extend": {},
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427200,
"deleteAt": -1,
"status": 0,
"groupInfo": {},
"entityCount": 0,
"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",
"effectiveSchemaDefine": "kind: DataSchema\nentity_type: demo_service\nproperties:\n- name: env\n type: string\n required: false\ncustom_properties:\n- name: business_owner\n title: 业务负责人\n type: string\n required: false\n extension_scope: custom\n writable_sources:\n - manual\n - gitops\n capabilities:\n display: true\n edit: true\n filter: false\n sort: false\n",
"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 | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 406 | ft.MissingParameters | 두 위치 지정 파라미터가 모두 비어 있음/누락됨 | 파라미터 누락 | 유형 UUID 또는 코드를 전달하고, 템플릿은 entityTypeUUID=default를 전달합니다. |
| 404 | ft.NotFoundCatalogEntityType | 대상 유형이 현재 가시 범위에 없거나 삭제되었거나, default 템플릿이 구성되지 않음 | 지정된 엔터티 유형을 찾을 수 없음 | 이 워크스페이스의 유형 목록에서 다시 선택합니다. 템플릿이 없으면 관리자에게 문의하며, 엔터티 URN으로 대체할 수 없습니다. |
| 500 | ft.InternalServerError | 유형 읽기, 엔터티 수 집계, 과거 설정/원본 Schema 파싱 또는 포맷팅 실패 | 내부 오류 | traceId와 유형/필터 조건을 보존하고 과거 정의 및 조회 서비스를 확인합니다. 이는 읽기 실패이며 이번에 설정이 저장되었다는 의미가 아닙니다. |
| 406 | ft.InvalidParameter | 기존 customProperties YAML/필드 이름/유형/capabilities 구조가 유효하지 않아 유효 Schema 생성 시 실패 | 파라미터 {}가 유효하지 않음 |
관리자가 현재 유형의 base Schema와 customProperties 원문을 확인하여 필드 충돌/구조를 수정합니다. 요청 위치가 올바르면 UUID를 반복해서 바꾸지 않습니다. |