통합 카탈로그 엔터티 유형 수정¶
POST /api/v1/unified_catalog/entity_type_cfg/{entity_type_uuid}/modify
개요¶
사용자 정의 기본 정의 및 현재 워크스페이스 유형 재정의 설정/헬스 정책을 수정합니다.
호출 전 준비 및 사용 단계¶
먼저 GET으로 원본 정의와 현재 워크스페이스 재정의를 백업하고, 반환된 uuid를 사용합니다. entityType 인코딩은 변경할 수 없습니다. 사용자 정의 유형은 이름/설명/Schema/View/extend를 변경할 수 있습니다. 공식 유형에서는 이러한 기본 필드가 적용되지 않으며, 워크스페이스 extraConfig/customProperties/healthConfig를 지원합니다. 생략한 필드는 유지되며, extraConfig/extend는 비어 있지 않으면 전체 교체되고 {}는 비웁니다. customProperties는 빈 문자열이면 비웁니다.
healthConfig는 mode를 명시해야 합니다. system은 default/func/disabled를 허용하고, 그 외 유형은 func/disabled만 허용합니다. funcId는 현재 워크스페이스의 삭제되지 않은 함수여야 하며, 저장 시 함수를 실행하지 않습니다. 헬스 정책을 변경하면 이전 계산 세대가 무효화됩니다. 비활성화 후 조회는 즉시 유효한 비활성 상태로 처리되며, 과거 결과는 비동기적으로 재설정됩니다. 설정 트랜잭션과 후속 세대/보상 스케줄링은 완전히 원자적이지 않습니다. 500이 발생하면 먼저 GET으로 확인한 후 처리합니다. 공개 API는 프런트엔드의 entityStatusConfig를 지원하지 않으며, 해당 effectiveViewDefine도 반환하지 않습니다.
다음 경로는 필드 값 내부의 YAML 텍스트에 위치하며, 별도의 JSON Body 필드가 아닙니다. 먼저 default 생성 템플릿 또는 기존 원본 설정에서 값을 가져와 필요한 부분만 수정합니다.
| YAML 경로 | 값, 기본값 및 출처 |
|---|---|
| schemaDefine.properties[] | base 필드 객체 배열입니다. 일반적으로 name, type, required 및 title을 사용합니다. 이름/유형은 해당 엔터티의 비즈니스 Schema에서 가져오며, 엔터티 속성 값으로 정의를 대체할 수 없습니다. type은 실제 데이터와 일치해야 하며, Studio 메타데이터 처리의 기본값은 string입니다. 추가 Schema 확장은 원본 템플릿에 따라 유지합니다. |
| schemaDefine.properties[].name/type/required/title | name은 필드 코드입니다. type은 실제 DataSchema 유형입니다. required는 불리언(기본값 false)입니다. title은 문자열 또는 언어-텍스트 객체일 수 있습니다. 선언은 모든 엔터티 쓰기 시의 필드별 비즈니스 검증을 대체하지 않습니다. |
| viewDefine.layout[] | 표시 레이아웃 항목 배열입니다. 일반적으로 group 객체(display_name, fields) 또는 직접 bind/title 노드를 사용하며, 내보내기도 이를 기준으로 열을 선택합니다. |
| viewDefine.layout[].group.fields[] | 필드 컨트롤 배열입니다. bind는 실제 Schema 필드를 참조하고, title은 문자열/현지화 객체이며, ui_type 및 기타 속성은 원본 템플릿/UI 기능을 기준으로 합니다. fields는 원본 정의에 따라 중첩할 수 있습니다. 서버는 각 컨트롤의 효과를 일괄 검증하지 않습니다. |
| customProperties.custom_properties[] | 사용자 정의 필드 객체이며 최상위 배열과 호환됩니다. 빈 텍스트는 필드가 없음을 의미합니다. 원문을 저장하며 기본값을 원본 YAML에 자동으로 다시 쓰지 않습니다. |
| custom_properties[].name | 비즈니스 필드 이름으로, 필수이며 비어 있으면 안 되고 숫자/영문자/_/-만 사용할 수 있습니다. base properties 및 동일 배열 내에서 중복될 수 없으며, 점/공백을 포함할 수 없습니다. |
| custom_properties[].type | 필수이며 비어 있지 않은 유형 이름입니다. 실제 필드에 따라 string 등을 선택하며, 저장 시 통일된 열거형을 강제하지 않고 임의 유형이 모두 UI에서 지원됨을 의미하지도 않습니다. |
| custom_properties[].title | 선택적 표시 제목으로, 문자열 또는 zh-CN/en-US와 같은 언어 텍스트 객체입니다. 생략하면 표시 시 필드 이름으로 대체될 수 있습니다. |
| custom_properties[].required | 선택 사항이며 기본값은 false입니다. 불리언 또는 true/1/yes/y/on 등의 불리언 문자열은 유효 계층에서 정규화됩니다. |
| custom_properties[].extension_scope | 선택 사항이며, 생략/빈 값은 유효 계층에서 custom입니다. 원본 Schema 확장 용도에 따라 사용합니다. |
| custom_properties[].writable_sources[] | 선택적 배열로, 각 항목은 manual/gitops 등 실제 쓰기 소스 식별자입니다. 공백은 제거하고 빈 항목은 건너뛰며, 생략 시 생성하지 않습니다. 이는 Schema 기능 선언이며 현재 API 인증 범위를 확장하지 않습니다. |
| custom_properties[].capabilities | 선택적 객체입니다. display/edit/filter/sort는 표시, 편집, 필터링, 정렬 기능의 불리언 값이며, 존재할 때 정규화됩니다. 제공되지 않은 키는 자동으로 일괄 보완되지 않습니다. 기타 확장 값은 원본 정의에 따라 유지합니다. |
| custom_properties[].기타 필드 | DataSchema에 이미 있는 확장에 따라 유지합니다(예: allowed_values, items 등). 저장 성공만으로 모든 소비자가 이를 지원한다고 판단해서는 안 됩니다. |
요청에서는 위 YAML을 문자열로 인코딩합니다. 아래 예시의 줄바꿈은 curl JSON에서 이스케이프되며, 서버는 텍스트로 파싱합니다. 로컬 파일 경로를 제출하거나 YAML을 JSON 객체로 펼쳐서 제출하지 마십시오.
경로 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| entity_type_uuid | string | Y | 경로 필수이며, 유형은 enty_ UUID이고 인코딩 또는 엔터티 URN이 아닙니다. 예: enty_example가져오기 또는 입력 방법: 현재 워크스페이스 유형 목록의 items[].uuid에서 대상을 가져옵니다. |
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| extraConfig.telemetrySelectors | array | 기존 확장 예시 키로, 소비자 정의 구조를 따르며 엔터티 실시간 조회 결과가 아닙니다. 키를 생략하면 전체 교체로 인해 기존 설정이 손실되므로 먼저 GET하십시오. 예: []가져오기 또는 입력 방법: 현재 유형의 기존 텔레메트리 연관 설정에서 전체 항목을 복사합니다. |
|
| extraConfig.telemetrySelectors[*] | JSON | 동적 객체는 원본 소비 설정에 따라 유지되며, 예시가 모든 시나리오에서 source/query 프로토콜을 강제로 통일하는 것은 아닙니다. 예: {"source": "logging", "query": "service:api"}가져오기 또는 입력 방법: 현재 비즈니스에서 검증된 텔레메트리 연관 항목입니다. |
|
| extraConfig.disabledBuiltInViews | array | 기존 확장 예시 키이며, 요소는 실제 뷰 식별자를 사용하고 통일된 열거형을 임의로 만들지 않습니다. []는 이 객체에서 해당 뷰를 비활성화하지 않음을 의미합니다. 예: []가져오기 또는 입력 방법: 기존 유형의 extraConfig 또는 UI에서 지원하는 내장 뷰 식별자에서 선택합니다. |
|
| extraConfig.disabledBuiltInViews[*] | string | 개별 비활성화 항목입니다. 적용 여부는 해당 UI 소비에 따르며, 이 API의 권한 설정이 아닙니다. 예: view_example가져오기 또는 입력 방법: 기존 내장 뷰의 실제 식별자입니다. |
|
| extraConfig.기타 설정 키 | JSON | 동적 확장 값은 유지됩니다. 통일된 기본값이나 열거형은 없습니다. 예: {}가져오기 또는 입력 방법: 현재 유형 상세/소비 기능 설정 설명에서 가져옵니다. |
|
| healthConfig.mode | string | healthConfig를 제공할 때 비즈니스상 필수입니다. default는 system만 허용합니다. disabled로 전환하면 즉시 비활성 상태로 읽히며, 동시에 과거 결과를 비동기적으로 재설정하고 모든 함수를 동기적으로 실행하지는 않습니다. 예: disabled가져오기 또는 입력 방법: system 기본 계산은 default, 자체 계산은 func, 비활성화는 disabled를 사용합니다. |
|
| healthConfig.funcId | string | func 모드에서는 비즈니스상 필수입니다. 다른 모드에서는 무시되고 저장 정규 구조에서 제거되며, 표시 이름/소스를 채우지 않습니다. 저장 시 존재 여부만 확인하고 검수 함수를 즉시 실행하지 않습니다. 예: func_example가져오기 또는 입력 방법: 현재 워크스페이스의 Func 함수 관리에서 삭제되지 않은 함수 UUID를 가져와 헬스 점수 규약을 충족하는지 확인합니다. |
|
| extend.확장 필드 | JSON | 동적으로 유지되며 통일된 기본값/열거형이 없고, 임의 값이 기능에서 소비된다고 보장하지 않습니다. 예: value가져오기 또는 입력 방법: 해당 사용자 정의 기능의 실제 규약 또는 기존 레코드에서 가져옵니다. |
|
| customProperties | string | 선택적 YAML 텍스트 문자열로 원문/주석을 유지합니다. 생성 시 생략하면 빈 문자열, 수정 시 생략하면 유지, 빈 문자열이면 비웁니다. custom_properties 배열을 권장하며 최상위 배열과 호환됩니다. 필드 이름은 base properties 또는 이 배열 내에서 중복될 수 없습니다. 펼친 객체를 Body 값으로 직접 사용하지 마십시오. null 허용: False 예: "# 원문과 주석 보존\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"가져오기 또는 입력 방법: 현재 워크스페이스 상세의 원본 customProperties 백업에서 가져오거나 아래 임베드된 YAML 형식에 따라 필드를 추가합니다. |
|
| description | string | 선택 사항이며 최대 512 가중치 문자입니다. 생성 시 생략하면 빈 문자열, 수정 시 생략하면 유지, 빈 문자열이면 비웁니다. 공식 유형은 이 수정을 무시합니다. null 허용: False 최대 길이: 512 예: 业务服务目录가져오기 또는 입력 방법: 비즈니스 담당자가 유형 용도 설명을 제공합니다. |
|
| extend | json | 선택적 동적 객체입니다. 생성 시 기본값은 {}입니다. 사용자 정의 수정 시 생략하면 유지, {}는 비우기, 비어 있지 않으면 전체 교체합니다. 공식 기본 유형은 이 필드를 무시하며 통합 스위치로 사용하지 않습니다. null 허용: False 예: {}가져오기 또는 입력 방법: 현재 사용자 정의 유형의 extend에서 전체 복사하거나 비즈니스 담당자가 확장 설정을 제공합니다. |
|
| extraConfig | json | 선택적 동적 워크스페이스 재정의 객체입니다. 생성 시 기본값은 {}입니다. 수정 시 생략하면 유지, {}는 전체 비우기, 비어 있지 않으면 전체 교체하며 깊은 병합은 하지 않습니다. 공식 유형도 지원하며 다른 워크스페이스의 공식 기본 정의를 변경하지 않습니다. 서버는 모든 동적 키의 의미를 일괄 검증하지 않습니다. null 허용: False 예: {"telemetrySelectors": [], "disabledBuiltInViews": []}가져오기 또는 입력 방법: 우선 현재 워크스페이스의 동일 유형 상세 extraConfig에서 전체 백업하고, 실제 프런트엔드 뷰/텔레메트리 설정 요구에 따라 조정합니다. |
|
| healthConfig | json | 수정 시에만 지원하며, 생략하면 유지됩니다. system은 default/func/disabled를 사용할 수 있고, 다른 유형은 func/disabled만 사용할 수 있습니다. {}는 유지가 아니라 잘못된 모드입니다. 모든 유형의 기능은 항상 활성화되며 과거 정리 준비를 기다리지 않습니다. null 허용: False 예: {"mode": "disabled"}가져오기 또는 입력 방법: 유형 비즈니스에 따라 계산 정책을 선택하고, 상세의 healthConfig에서 현재 유효 값을 확인합니다. |
|
| name | string | 선택 사항이며 최대 128 가중치 문자입니다. 생성 시 생략하면 빈 문자열이 됩니다. 수정 시 전달된 값은 공백을 제거하며, 빈 문자열이면 비우고 생략하면 유지합니다. 공식 유형에 이 필드를 전달해도 공식 이름을 덮어쓰지 않습니다. null 허용: False 최대 길이: 128 예: 示例服务가져오기 또는 입력 방법: 비즈니스 담당자가 유형 표시 이름을 제공하며, entityType 인코딩을 대체하지 않습니다. |
|
| schemaDefine | string | 선택적 YAML 객체 텍스트이며 properties는 배열이어야 합니다. 생성 시 생략/빈 문자열이면 템플릿에서 보완하고 {entity_type}을 요청 인코딩으로 교체합니다. 사용자 정의 유형 수정 시에만 적용되며, 생략하면 유지, 빈 문자열이면 원본 정의를 비웁니다. effectiveSchemaDefine을 원본 schema로 다시 쓸 수 없습니다. null 허용: False 예: "kind: DataSchema\nentity_type: demo_service\nproperties:\n - name: env\n type: string\n required: false\n"가져오기 또는 입력 방법: 먼저 entityTypeUUID=default로 템플릿을 가져오거나 GET으로 대상 원본 DataSchema YAML을 백업합니다. |
|
| viewDefine | string | 선택적 YAML 객체 텍스트이며 layout/각 수준 fields는 배열이어야 합니다. 생성 시 생략/빈 문자열이면 템플릿에서 보완하고 {entity_type}을 교체합니다. 수정 시 사용자 정의에만 적용되며, 생략하면 유지, 빈 문자열이면 비웁니다. effectiveViewDefine이 아닙니다. 열/컨트롤의 추가 확장은 원본 템플릿 구조를 유지하십시오. null 허용: False 예: "kind: UIView\nlayout:\n - group:\n display_name: 基础信息\n fields:\n - bind: env\n title: 环境\n ui_type: input\n"가져오기 또는 입력 방법: 생성 템플릿 또는 현재 유형의 원본 UIView YAML에서 가져옵니다. |
매개변수 추가 설명¶
경로 매개변수 설명
| 매개변수 이름 | type | 필수 | 설명 |
|---|---|---|---|
| entity_type_uuid | string | 예 | 대상 엔터티 유형 UUID |
요청 본문 매개변수 설명
| 매개변수 이름 | type | 필수 | 설명 |
|---|---|---|---|
| name | string | 아니요 | 엔터티 유형 표시 이름 |
| description | string | 아니요 | 엔터티 유형 설명 |
| extraConfig | json | 아니요 | 현재 워크스페이스의 추가 설정 |
| customProperties | string | 아니요 | 엔터티 유형이 현재 워크스페이스에 추가하는 DataSchema 사용자 정의 필드 YAML 텍스트이며, 최상위가 custom_properties인 형식을 권장합니다 |
| schemaDefine | string | 아니요 | DataSchema YAML 텍스트 |
| viewDefine | string | 아니요 | UIView YAML 텍스트 |
| extend | json | 아니요 | 확장 필드 |
호출 시 유의 사항
- 기본 유형은
extraConfig및customProperties수정을 지원합니다. - 모든 엔터티 유형은 항상
healthConfig수정을 지원합니다. system은default/func/disabled를 지원하고, 다른 유형은func/disabled를 지원합니다. 백그라운드 readiness 정리 진행 상황에 의존하지 않습니다. - 사용자 정의 유형은
name,description,schemaDefine,viewDefine,extend를 수정할 수 있으며,extraConfig와customProperties도 동시에 수정할 수 있습니다. extraConfig는 전체 객체를 전달하는 것을 권장하며, 부분 patch 방식으로 값을 전달하는 것은 권장하지 않습니다.customProperties는 최상위custom_properties배열을 포함하는 YAML 텍스트를 전달하는 것을 권장합니다. 이전 호출과의 호환성을 위해 최상위 YAML 배열도 허용합니다.customProperties필드 이름은 현재 엔터티 유형 DataSchemaproperties의 필드와 중복될 수 없습니다. 필드는 YAML 텍스트로 저장되며 주석은 원문 그대로 유지됩니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity_type_cfg/enty_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"示例服务","extraConfig":{},"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","healthConfig":{"mode":"disabled"}}'
응답¶
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 | system의 기본값은 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 | 요청 필드 누락 또는 필드 값이 선언된 검증 조건을 위반함 | 매개변수 파싱 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | Body 최상위가 JSON 객체가 아님 | 일부 json 파일 형식 오류 | 예시에 따라 객체를 제출하고 배열/문자열을 사용하지 않습니다. |
| 406 | ft.InvalidParameter | 사용자 정의 필드 YAML/이름/유형/기능 구조가 잘못됨, 또는 Schema/View 구조에서 메타데이터를 생성할 수 없음; healthConfig.mode가 잘못됨/비-system에서 default 사용, func 모드에서 funcId 누락 또는 현재 워크스페이스의 삭제되지 않은 함수가 아님 | 매개변수 {}가 유효하지 않음 |
아래 YAML 필드 표와 원본 템플릿에 따라 수정하고, base 필드 중복 이름, 루트 객체/배열 및 유효 유형을 확인합니다. 먼저 유형에서 허용하는 헬스 mode를 확인하고, 현재 워크스페이스의 Func 관리에서 삭제되지 않은 함수 UUID를 가져옵니다. 이름/다른 워크스페이스 함수를 입력하지 마십시오. |
| 500 | ft.InternalServerError | 설정 읽기/쓰기, 원본 과거 YAML 처리, 카운트 조회, 잠금/헬스 세대 또는 보상 작업의 포착되지 않은 실패 | 내부 오류 | 먼저 UUID로 현재 상태를 다시 읽습니다. 오류가 제출 후 발생한 경우 설정이 이미 적용되었을 수 있습니다. traceId를 유지하고 무작정 반복 생성하지 마십시오. |
| 404 | ft.NotFoundCatalogEntityType | 유형 UUID가 존재하지 않음/삭제됨 또는 표시되지 않음 | 지정된 엔터티 유형을 찾을 수 없음 | 유형 목록에서 현재 표시되는 UUID를 가져옵니다. |
| 429 | ft.OperationTooFrequently | 유형 수정 또는 헬스 쓰기 상호 배타 잠금 경합 | 작업이 너무 빈번합니다. 잠시 후 다시 시도하십시오 | 제한적으로 백오프하고, 먼저 현재 설정을 다시 읽은 후 제출합니다. |