콘텐츠로 이동

수정



POST /api/v1/field_cfg/{field_uuid}/modify

개요

현재 워크스페이스의 사용자 정의 필드 설정 및 다국어 표시를 수정합니다.

호출 전 및 사용 단계

대상 워크스페이스의 API Key를 사용합니다. 이 설정은 기존 필드에 표시 별칭, 설명, 단위 및 카테고리를 추가하며, 수집 필드를 생성하거나 실제 데이터 유형을 변경하거나 과거 데이터를 백필하지 않습니다. 필드 소스가 같고 이름의 대소문자가 완전히 동일한 사용자 정의 설정은 중복될 수 없으며, 소스가 다르면 동일한 이름을 사용할 수 있습니다.

수정 시 name, fieldType, fieldSource, category, unit을 완전히 지정해야 하며, 이는 해당 설정 항목에 대한 덮어쓰기입니다. alias/desc의 다국어 데이터는 병합되며, 제출하지 않은 언어는 유지되고, 명시적 빈 값 이후 표시가 폴백될 수 있습니다. 현재 워크스페이스의 유효한 사용자 정의 레코드만 허용되며, 기본 제공 레코드는 수정할 수 없습니다.

쓰기 제출 후 캐시를 지웁니다. 데이터베이스는 성공했지만 캐시 삭제가 실패하면 여전히 500을 반환할 수 있습니다. 실패 시 먼저 목록/상세에서 생성 또는 수정되었는지 확인하고 바로 재생성하지 마십시오. 동일 이름 동시성 보호로 인해 일시적으로 거부될 수 있습니다. 성공 후 다시 읽어 설정을 확인하십시오. 데이터 조회 표시의 갱신은 해당 캐시와 조회 경로에 따라 달라집니다.

라우트 파라미터

파라미터 이름 유형 필수 설명
field_uuid string Y 현재 워크스페이스의 유효한 필드 설정 UUID입니다. 기본 제공 설정은 일반적으로 시스템 워크스페이스에 속하며, 목록에 표시된다고 해서 현재 워크스페이스에서 상세 정보를 읽을 수 있는 것은 아닙니다.
예: field_example
가져오기 또는 입력 방법: 필드 목록에서 sysField=0인 대상 행의 uuid를 읽고, 필드 이름은 사용하지 않습니다.

요청 헤더

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

Body 요청 파라미터

파라미터 이름 유형 필수 설명
aliasI18n.zh string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예: 主机
가져오기 또는 입력 방법: zh 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
aliasI18n.en string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예: Host
가져오기 또는 입력 방법: en 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
aliasI18n.zh-hant string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: zh-hant 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
aliasI18n.id string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: id 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
aliasI18n.ja string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: ja 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
aliasI18n.ko string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: ko 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
descI18n.zh string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예: 主机
가져오기 또는 입력 방법: zh 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
descI18n.en string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예: Host
가져오기 또는 입력 방법: en 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
descI18n.zh-hant string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: zh-hant 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
descI18n.id string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: id 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
descI18n.ja string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: ja 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
descI18n.ko string 또는 null 이 언어만 업데이트합니다. 빈 문자열 또는 null은 이 언어의 기존 값을 지우며, 실제 표시에서는 여전히 다른 언어로 폴백될 수 있습니다.
예:
가져오기 또는 입력 방법: ko 표시 텍스트를 입력합니다. 이 언어를 수정할 필요가 없으면 해당 키를 생략합니다.
alias string 생성 시 필수이며, 수정 시 생략할 수 있고 기존 언어 값은 유지됩니다. 제출 시 비어 있지 않아야 하며 최대 256자입니다. 같은 요청에서 aliasI18n.zh가 우선합니다.
빈 문자열 허용: False
null 허용: False
최대 길이: 256
예: 主机
가져오기 또는 입력 방법: 콘솔에 표시할 중국어 별칭을 입력하고, 영어 및 기타 언어는 aliasI18n에 입력합니다.
aliasI18n object 선택적 객체입니다. 알 수 없는 언어 키는 무시되고, 값은 문자열을 권장하며 null은 빈 문자열로 변환됩니다. 제출한 언어만 병합되고 다른 언어는 유지됩니다. 호환성을 위해 alias/aliasEn은 zh/en 간 상호 폴백됩니다.
null 허용: False
예: {"en": "Host"}
가져오기 또는 입력 방법: 실제 지원 언어에 따라 작성하고, 업데이트할 언어만 제출합니다.
category string 선택 사항이며, 생략하면 기본값은 system입니다. 수정 시 생략해도 system으로 재설정되며 기존 카테고리를 유지하지 않습니다.
빈 문자열 허용: False
null 허용: False
선택 가능한 값: ['system', 'business', 'other']
예: business
가져오기 또는 입력 방법: 용도에 따라 system/business/other를 선택합니다.
coverInner boolean 선택적 불리언입니다. 과거 확인 분기는 비활성화되었습니다. false는 동일한 이름의 사용자 정의 필드 생성을 막지 않으며 need_confirm도 반환하지 않습니다. 목록에서는 여전히 사용자 정의가 기본 제공을 덮어쓰지만, 기본 제공 레코드는 수정하지 않습니다.
null 허용: False
예: false
가져오기 또는 입력 방법: 현재 구현에서는 생략할 수 있으며, 쓰기 후 목록의 coverInner에서 덮어쓰기 여부를 확인합니다.
desc string 선택 사항이며 최대 3000자이고 빈 문자열을 허용합니다. 수정 시 생략하면 기존 언어 값을 유지하며, 명시적 descI18n.zh가 우선합니다.
빈 문자열 허용: True
null 허용: False
최대 길이: 3000
예: 主机名称
가져오기 또는 입력 방법: 필드의 비즈니스 의미/획득 방식을 입력하고, 다른 언어는 descI18n에 입력합니다.
descI18n object 선택적 객체이며, 언어 병합/지우기/폴백은 aliasI18n과 동일합니다. OpenAPI는 독립적인 descEn 파라미터를 허용하지 않으므로 영어 설명은 이 객체의 en 키에 입력합니다.
null 허용: False
예: {"en": "Host name"}
가져오기 또는 입력 방법: 언어 코드별로 추가, 업데이트 또는 지워야 할 설명을 제출합니다.
fieldSource string 선택 사항이며, 생략하면 빈 문자열입니다. lineage/logging/object/custom_object/keyevent/tracing/rum/security/network/billing 및 빈 값을 지원합니다. 수정 시 생략하면 일반 소스가 되며 기존 값을 유지하지 않습니다.
빈 문자열 허용: True
null 허용: False
선택 가능한 값: ['lineage', 'logging', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'billing']
예: logging
가져오기 또는 입력 방법: 대상 데이터 카테고리에 따라 선택하며, 범용 필드는 빈 문자열을 명시적으로 입력합니다.
fieldType string 선언은 선택 사항이지만 항상 명시적으로 제출하는 것이 좋습니다. 생성 시 생략하면 빈 문자열이 저장되고, 수정 시 생략하면 500이 발생합니다. string인 경우 unit은 강제로 비어 있으며, 다른 유형은 전달된 unit을 사용합니다. 과거 number/time/percent는 현재 쓰기 인터페이스의 열거형 값으로 직접 제출할 수 없습니다.
빈 문자열 허용: True
null 허용: False
선택 가능한 값: ['text', 'int', 'float', 'boolean', 'string', 'long']
예: string
가져오기 또는 입력 방법: 실제 필드에 따라 text/int/float/boolean/string/long을 선택합니다.
name string Y 필수이며 비어 있지 않아야 하고 최대 256자이며 대소문자를 구분합니다. 생성 시 기본 한자 범위를 포함하는 이름은 거부됩니다. 수정 시에는 동일한 중국어 검사가 없으므로 실제 비중국어 필드 이름을 유지하는 것이 좋습니다.
빈 문자열 허용: False
null 허용: False
최대 길이: 256
예: host
가져오기 또는 입력 방법: 실제 수집 필드 이름을 입력합니다. 먼저 필드 목록에서 동일 소스 및 동일 이름 설정을 확인합니다.
unit string 선택 사항이며 최대 256자이고 기본값은 빈 문자열입니다. 수정 시 생략하면 비워지며, fieldType=string인 경우 무엇을 전달하든 비워집니다. 이 진입점에서는 InvalidUnit 비즈니스 검증을 수행하지 않습니다.
빈 문자열 허용: True
null 허용: False
최대 길이: 256
예:
가져오기 또는 입력 방법: 단위 설명에 따라 유효한 표시 단위 식별자를 선택하고, string인 경우 빈 문자열을 입력합니다.

파라미터 추가 설명

단위 정보는 단위 설명을 참조하십시오. 현재 need_confirm 확인은 필요하지 않으며, coverInner는 목록 덮어쓰기를 제어하지 않습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/field_cfg/field_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"host","alias":"主机","aliasI18n":{"en":"Host"},"fieldType":"string","fieldSource":"logging","category":"business","unit":"","desc":"主机名称","descI18n":{"en":"Host name"},"coverInner":false}'

응답

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

필드 유형 설명
content.id integer 레코드 번호이며 인터페이스 주소 지정에는 사용되지 않습니다.
content.workspaceUUID string 설정 소속 워크스페이스, 기본 제공 설정은 시스템 워크스페이스에 속합니다.
content.status integer 레코드 상태, 정상 0, 소프트 삭제 3; 이 상세 정보는 유효하고 현재 워크스페이스에 속한 레코드만 반환합니다.
content.deleteAt integer 삭제 시간(Unix 초), 삭제되지 않은 경우 -1입니다.
content.declaration object 현재 호출 워크스페이스의 공통 선언입니다.
content.uuid string 필드 설정 UUID이며 이후 작업에는 이 값을 사용하고 실제 필드 이름은 사용하지 않습니다.
content.name string 실제 필드 이름, 대소문자 구분.
content.alias string 별칭입니다. 목록에서는 요청 언어에 따라 표시되며, 상세/생성/수정에서는 호환 필드 값을 유지합니다.
content.aliasEn string 영어 별칭 호환 필드, 중국어로 폴백될 수 있습니다.
content.aliasI18n object 6개 언어 원본 별칭 매핑, 빈 언어 값이 표시도 반드시 비어 있음을 의미하지는 않습니다.
content.desc string 설명입니다. 목록에서는 요청 언어에 따라 표시되며, 나머지 응답에서는 호환 필드 값입니다.
content.descEn string 영어 설명 호환 필드, 중국어로 폴백될 수 있습니다.
content.descI18n object 6개 언어 원본 설명 매핑.
content.fieldType string 설정된 데이터 유형이며 실제 수집 필드 유형을 변경하지 않습니다. 과거 기본 제공 레코드는 생성 Body 이외의 값을 가질 수 있습니다.
content.fieldSource string 적용 소스, 빈 문자열은 범용 설정을 나타냅니다.
content.unit string 표시 단위, fieldType=string 저장 시 강제로 비어 있습니다.
content.sysField integer 1 기본 제공, 0 사용자 정의. 기본 제공 설정은 이 인터페이스로 수정/삭제할 수 없습니다.
content.category string system 시스템 필드, business 비즈니스 필드, other 기타; 이전 레코드는 비어 있을 수 있습니다.
content.creator string 생성 주체, API Key 또는 시스템 주체일 수 있습니다.
content.updator string 업데이트 주체, 아직 업데이트되지 않은 경우 빈 문자열입니다.
content.createAt integer 생성 시간, Unix 초.
content.updateAt integer 업데이트 시간, Unix 초; 아직 업데이트되지 않은 경우 -1일 수 있습니다.
content.aliasI18n.zh string zh 언어 원본 별칭, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.aliasI18n.en string en 언어 원본 별칭, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.aliasI18n.zh-hant string zh-hant 언어 원본 별칭, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.aliasI18n.id string id 언어 원본 별칭, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.aliasI18n.ja string ja 언어 원본 별칭, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.aliasI18n.ko string ko 언어 원본 별칭, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.descI18n.zh string zh 언어 원본 설명, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.descI18n.en string en 언어 원본 설명, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.descI18n.zh-hant string zh-hant 언어 원본 설명, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.descI18n.id string id 언어 원본 설명, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.descI18n.ja string ja 언어 원본 설명, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
content.descI18n.ko string ko 언어 원본 설명, 제공되지 않은 경우 일반적으로 비어 있으며 목록 표시는 언어에 따라 폴백됩니다.
{
  "code": 200,
  "content": {
    "id": 10,
    "uuid": "field_example",
    "workspaceUUID": "wksp_example",
    "name": "host",
    "alias": "主机",
    "aliasEn": "Host",
    "aliasI18n": {
      "zh": "主机",
      "en": "Host",
      "zh-hant": "主機",
      "id": "",
      "ja": "",
      "ko": ""
    },
    "desc": "主机名称",
    "descEn": "Host name",
    "descI18n": {
      "zh": "主机名称",
      "en": "Host name",
      "zh-hant": "主機名稱",
      "id": "",
      "ja": "",
      "ko": ""
    },
    "fieldType": "string",
    "fieldSource": "logging",
    "category": "business",
    "unit": "",
    "sysField": 0,
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.FieldCustomNameRepeat 동일 워크스페이스, 동일 소스, 동일 이름의 사용자 정의 설정이 이미 존재하거나 동시 생성/수정이 거부됨 해당 사용자 정의 필드 이름이 이미 존재합니다: {} 먼저 소스와 이름으로 기존 레코드를 조회하고 동일 이름 동시 제출을 피합니다. 결과 확인 후 수정 또는 이름 변경을 결정합니다.
500 ft.InternalServerError 저장, 캐시 또는 응답 구성 실패, 수정 시 fieldType을 제출하지 않은 경우에도 처리되지 않은 예외가 발생할 수 있음 내부 오류 수정 시 유효한 fieldType을 명시적으로 제출하고, 기타 실패 시 traceId를 보존합니다. 쓰기 요청 실패 시 먼저 다시 읽어 확인하고 무작정 재생성하지 마십시오.
400 ft.FieldNotFound UUID가 현재 워크스페이스에 속하지 않거나 레코드가 존재하지 않거나 삭제됨 지정된 필드를 찾을 수 없습니다 현재 워크스페이스의 필드 목록에서 사용자 정의 설정 UUID를 가져옵니다. 시스템 워크스페이스의 UUID로 작업할 수 없습니다.
406 ft.NotSupportedModify 대상 유효 레코드가 시스템 기본 제공 필드로 표시됨 시스템 기본 제공 필드는 수정할 수 없습니다 사용자 정의 필드만 수정합니다. 표시를 조정해야 하는 경우 동일 소스 및 동일 이름의 사용자 정의 설정을 생성합니다.

문서 평가

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