콘텐츠로 이동

추가



POST /api/v1/field_cfg/add

개요

현재 워크스페이스에 사용자 정의 필드 설명, 별칭 및 표시 단위 구성을 생성합니다.

호출 전 및 사용 단계

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

생성 전에 소스와 name 기준으로 기존 사용자 정의 구성을 확인합니다. coverInner=false여도 동일한 이름의 기본 제공 구성을 숨기는 것을 막지 않습니다. 성공 시 need_confirm이 아닌 새로 생성된 레코드를 반환합니다. sysField는 서버에서 처리하므로 Body에 sysField를 제출하지 마십시오.

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

요청 헤더

매개변수 이름 유형 필수 설명
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 Y 새로 추가할 때 필수이며, 수정 시 생략할 수 있고 기존 언어를 유지합니다. 제출 시 비어 있지 않아야 하며 최대 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는 현재 쓰기 API의 열거형으로 직접 제출할 수 없습니다.
빈 문자열 허용: 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는 목록 덮어쓰기를 제어하지 않습니다.

3. 필드 관리 사용 설명

3.1. 필드 관리는 필드 쿼리에 필드 설명을 제공합니다.
아래 함수 쿼리를 수행할 때 필드 설명을 반환하려면 fieldTagDescNeeded(필드 위치는 queries와 동일한 수준)를 true로 지정해야 합니다.
반환되는 series에는 value_desc(위치는 values, columns와 동일한 수준) 필드가 추가됩니다.

함수 필드 소스/fieldSource
SHOW_FIELD(namespace=...) namespace에 따라 해당 필드 소스를 사용합니다. L은 logging, LN은 lineage이며, 전용 SHOW 필드 함수의 소스 매핑과 호환됩니다.
SHOW_TAG_KEY ""
SHOW_OBJECT_HISTORY_FIELD "object"
SHOW_BACKUP_LOG_FIELD "logging"
SHOW_PROFILING_FIELD "tracing"
SHOW_OBJECT_FIELD "object"
SHOW_LOGGING_FIELD "logging"
SHOW_EVENT_FIELD "keyevent"
SHOW_TRACING_FIELD "tracing"
SHOW_RUM_FIELD "rum"
SHOW_CUSTOM_OBJECT_FIELD "custom_object"
SHOW_CUSTOM_OBJECT_HISTORY_FIELD "custom_object"
SHOW_NETWORK_FIELD "network"
SHOW_SECURITY_FIELD "security"
SHOW_UNRECOVERED_EVENT_FIELD "keyevent"
SHOW_TRACING_METRIC_FIELD "tracing"
SHOW_RUM_METRIC_FIELD "rum"
SHOW_NETWORK_METRIC_FIELD "network"

참고: SHOW_FIELD_KEY의 필드 설명은 사용자 정의 메트릭 구성과 datakit 측 measurements-meta.json을 사용합니다.

3.2. 필드 관리는 쿼리에 단위 정보를 제공합니다.

dql 쿼리 단위 로드(query_data 결과의 series에 units 추가):
메트릭 데이터를 쿼리할 때 로드되는 단위 정보는 사용자 정의 메트릭 필드이며, 공식 메트릭 필드(measurements-meta.json)를 덮어써서 산출됩니다.
비메트릭 데이터를 쿼리할 때 로드되는 단위 정보는 필드 관리에서 정의한 단위입니다.

3.3. 필드 관리가 단위 정보를 제공할 때의 쿼리 함수 설명

dql 쿼리를 수행할 때 사용하는 함수가 구성된 unitWhiteFuncs 함수 범위에 없으면 단위를 추가하지 않습니다. 예: count
unitWhiteFuncs에는 normal, special 두 가지 함수가 있습니다. special 함수를 사용할 때 단위에는 고정 접미사 /s가 추가되며, unit = {"unit": unit, "suffix": "/s"}입니다.
unitWhiteFuncs 함수 설명은 다음과 같습니다:

unitWhiteFuncs:
  normal:
    - avg
    - bottom
    - top
    - difference
    - non_negative_difference
    - distinct
    - first
    - last
    - max
    - min
    - percentile
    - sum
    - median
    - mode
    - spread
    - moving_average
    - abs
    - cumsum
    - moving_average
    - series_sum
    - round
    - window
  special:
    - derivative
    - non_negative_derivative
    - rate
    - irate

4. 필드 동일 이름 우선순위 설명

4.1. 사용자 정의 필드가 기본 제공 필드보다 우선합니다.
4.2. 구체적인 소스(fieldSource)가 일반 필드 소스보다 우선합니다.


요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/field_cfg/add' \
  -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 레코드 번호이며 API 주소 지정에는 사용하지 않습니다.
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은 사용자 정의입니다. 기본 제공 구성은 이 API로 수정/삭제할 수 없습니다.
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 쓰기, 제출 후 캐시 지우기 또는 응답 구성에 실패했습니다. 내부 오류 먼저 목록/상세에서 제출 상태를 확인한 후 재시도 여부를 결정하여 중복 생성을 피합니다.
406 ft.NotSupportedChinese 새로 추가하는 name에 기본 한자가 포함되어 있습니다. 중국어 필드 이름은 지원되지 않습니다. 실제 비중국어 필드 이름을 사용하고, 중국어 표시 이름은 alias에 입력합니다.

문서 평가

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