콘텐츠로 이동

통합 카탈로그 엔터티 유형 상세



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를 반복해서 바꾸지 않습니다.

문서 평가

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