콘텐츠로 이동

목록 조회



GET /api/v1/field_cfg/list

개요

현재 워크스페이스의 사용자 정의 필드 설정과 표시 가능한 기본 제공 필드 설정을 페이지 단위로 나열합니다.

호출 전 준비 및 사용 단계

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

이름/별칭 키워드로 검색하고 페이지별로 읽습니다. 사용자 정의 필드가 먼저 반환된 다음, 동일한 소스와 동일한 이름의 사용자 정의 설정으로 덮어쓰이지 않은 기본 제공 필드가 이어집니다. 각각 이름순으로 정렬되며 전체를 통합해 정렬하지 않습니다. search는 앞뒤 공백을 제거하며, 데이터베이스 LIKE의 %와 _는 여전히 와일드카드 의미를 가집니다. Accept-Language는 표시 언어를 선택합니다: zh/en/zh-Hant/id/ja/ko. 생략하면 사이트 기본값을 사용합니다. 중국어의 경우 이름/중국어 별칭을 검색하고, 영어의 경우 이름/영어 별칭을 검색하며, 나머지 네 언어는 현재 언어 별칭/설명과 중국어 및 영어 별칭도 검색합니다. 목록은 캐시를 강제하지 않으며, 빈 페이지가 반환되는 것은 정상적인 결과입니다. 두 필드 유형을 각각 검색한 후 덮어쓰기를 계산하며, search와 일치하지 않는 사용자 정의 덮어쓰기 항목은 숨김 처리에 참여하지 않습니다. 전체 덮어쓰기 관계를 확인할 때는 먼저 search를 비우세요. coverInner는 표시용 힌트일 뿐이며, 소스가 다른 동일 이름 행에도 true가 포함될 수 있으므로 이 키만으로 판단할 수 없습니다.

목록의 desc/alias는 언어 폴백에 따라 표시됩니다(zh→en, en→zh, zh-hant→zh→en, 나머지→en→zh). 다국어 매핑은 원래 값을 유지합니다. 수정 전에 전체 설정을 우선 보존하세요. sysField=1인 기본 제공 행은 참고용입니다.

요청 헤더

파라미터 이름 유형 필수 설명
Accept-Language string 선택 사항이며, 목록의 표시와 검색에 영향을 주지만 저장된 다국어 매핑은 변경하지 않습니다.
예: zh
가져오기 또는 입력 방법: 지원되는 요청 언어를 선택합니다. 생략하면 사이트 기본 언어를 사용합니다.
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예: <DF-API-KEY>
가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Query 요청 파라미터

파라미터 이름 유형 필수 설명
pageIndex integer 선택 사항이며 기본값은 1이고 최솟값은 1입니다.
null 허용: False
$minValue: 1
예: 1
가져오기 또는 입력 방법: 첫 요청에는 1을 입력하고, pageInfo.totalCount와 함께 페이지를 넘깁니다.
pageSize integer 선택 사항이며 컨트롤러 기본값은 100이고 최대값은 1000입니다.
null 허용: False
$maxValue: 1000
$minValue: 1
예: 20
가져오기 또는 입력 방법: 클라이언트 용량에 맞게 1~1000을 선택합니다.
search string 선택적 퍼지 검색이며, 필드 소스로 필터링하는 것이 아닙니다.
null 허용: False
예: host
가져오기 또는 입력 방법: 실제 이름 또는 별칭 키워드를 입력합니다. 생략하거나 빈 문자열이면 전체를 조회합니다.

파라미터 추가 설명

필드 관리 설정 우선순위: 동일 소스, 동일 이름인 경우 사용자 정의가 기본 제공을 덮어씁니다. 상세 조회 및 수정 시에는 설정 UUID를 사용해야 하며, 실제 수집 필드 이름은 여전히 name입니다.

요청 예시

curl --get 'https://openapi.guance.com/api/v1/field_cfg/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode search=host \
  --data-urlencode pageIndex=1 \
  --data-urlencode pageSize=20

응답

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

필드 유형 설명
content.data array<object> 현재 페이지의 필드 설정으로, 사용자 정의 필드가 먼저 오고 덮어쓰이지 않은 기본 제공 필드가 이어지며, 각각 이름순으로 정렬됩니다.
content.declaration object 워크스페이스 공통 선언입니다.
content.data[].uuid string 필드 설정 UUID입니다. 후속 작업에서는 이 값을 사용하며 실제 필드 이름이 아닙니다.
content.data[].name string 실제 필드 이름이며 대소문자를 구분합니다.
content.data[].alias string 별칭입니다. 목록에서는 요청 언어에 따라 표시되고, 상세/생성/수정에서는 호환 필드 값을 유지합니다.
content.data[].aliasEn string 영문 별칭 호환 필드이며, 중국어 값으로 폴백될 수 있습니다.
content.data[].aliasI18n object 6개 언어의 원본 별칭 매핑입니다. 언어 값이 비어 있다고 해서 표시도 반드시 비어 있는 것은 아닙니다.
content.data[].desc string 설명입니다. 목록에서는 요청 언어에 따라 표시되고, 나머지 응답에서는 호환 필드 값입니다.
content.data[].descEn string 영문 설명 호환 필드이며, 중국어 값으로 폴백될 수 있습니다.
content.data[].descI18n object 6개 언어의 원본 설명 매핑입니다.
content.data[].fieldType string 설정된 데이터 유형이며 실제 수집 필드 유형을 변경하지 않습니다. 기존 기본 제공 레코드는 생성 Body 외의 값을 가질 수 있습니다.
content.data[].fieldSource string 적용 소스이며, 빈 문자열은 공통 설정을 의미합니다.
content.data[].unit string 표시 단위입니다. fieldType=string으로 저장할 때는 강제로 빈 값으로 설정됩니다.
content.data[].sysField integer 1은 기본 제공, 0은 사용자 정의입니다. 기본 제공 설정은 이 API로 수정/삭제할 수 없습니다.
content.data[].category string system은 시스템 필드, business는 비즈니스 필드, other는 기타입니다. 오래된 레코드는 비어 있을 수 있습니다.
content.data[].creator string 생성 주체이며 API Key 또는 시스템 주체일 수 있습니다.
content.data[].updator string 수정 주체이며, 아직 수정되지 않은 경우 빈 문자열입니다.
content.data[].createAt integer 생성 시간, Unix 초.
content.data[].updateAt integer 수정 시간, Unix 초이며 아직 수정되지 않은 경우 -1일 수 있습니다.
content.data[].aliasI18n.zh string zh 언어의 원본 별칭이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].aliasI18n.en string en 언어의 원본 별칭이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].aliasI18n.zh-hant string zh-hant 언어의 원본 별칭이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].aliasI18n.id string id 언어의 원본 별칭이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].aliasI18n.ja string ja 언어의 원본 별칭이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].aliasI18n.ko string ko 언어의 원본 별칭이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].descI18n.zh string zh 언어의 원본 설명이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].descI18n.en string en 언어의 원본 설명이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].descI18n.zh-hant string zh-hant 언어의 원본 설명이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].descI18n.id string id 언어의 원본 설명이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].descI18n.ja string ja 언어의 원본 설명이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].descI18n.ko string ko 언어의 원본 설명이며, 제공되지 않은 경우 일반적으로 비어 있습니다. 목록 표시에서는 언어 폴백이 적용됩니다.
content.data[].coverInner boolean 선택적 표시 힌트로, 동일 소스 덮어쓰기를 단독으로 증명하기에는 부족합니다. 계산 시 이름만 기록되며, 소스가 다른 동일 이름의 사용자 정의 행에도 true가 포함될 수 있습니다. search를 비우고 fieldSource와 name을 함께 확인하세요. 다른 행에는 이 키가 없을 수 있습니다.
content.data[].creatorInfo object 주체 정보입니다. 조회되지 않으면 {}이며, 시스템 주체는 일부 키만 반환할 수 있습니다.
content.data[].creatorInfo.uuid string 주체 UUID입니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.status integer 주체 상태입니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.wsAccountStatus integer 워크스페이스 멤버 상태입니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.username string 사용자 이름 또는 Key 이름입니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.name string 이름입니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.email string 이메일 또는 Key 식별자이며 이메일 형식임을 보장하지 않습니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.mobile string 휴대폰 번호이며 비어 있을 수 있습니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.countryCode string 국가 코드이며 생략할 수 있습니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.iconUrl string 아이콘 URL이며 생략할 수 있습니다. 실제 반환값을 기준으로 합니다.
content.data[].creatorInfo.acntWsNickname string 워크스페이스 닉네임이며 생략할 수 있습니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo object 주체 정보입니다. 조회되지 않으면 {}이며, 시스템 주체는 일부 키만 반환할 수 있습니다.
content.data[].updatorInfo.uuid string 주체 UUID입니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.status integer 주체 상태입니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.wsAccountStatus integer 워크스페이스 멤버 상태입니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.username string 사용자 이름 또는 Key 이름입니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.name string 이름입니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.email string 이메일 또는 Key 식별자이며 이메일 형식임을 보장하지 않습니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.mobile string 휴대폰 번호이며 비어 있을 수 있습니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.countryCode string 국가 코드이며 생략할 수 있습니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.iconUrl string 아이콘 URL이며 생략할 수 있습니다. 실제 반환값을 기준으로 합니다.
content.data[].updatorInfo.acntWsNickname string 워크스페이스 닉네임이며 생략할 수 있습니다. 실제 반환값을 기준으로 합니다.
pageInfo.pageIndex integer 현재 페이지이며 1부터 시작합니다.
pageInfo.pageSize integer 페이지당 건수입니다.
pageInfo.count integer 현재 페이지 건수입니다.
pageInfo.totalCount integer 병합 및 기본 제공 필드 덮어쓰기 이후의 총 건수입니다.
{
  "code": 200,
  "content": {
    "data": [
      {
        "uuid": "field_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,
        "creator": "wsak_example",
        "updator": "",
        "createAt": 1785427200,
        "updateAt": -1,
        "creatorInfo": {},
        "updatorInfo": {}
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE",
  "pageInfo": {
    "pageIndex": 1,
    "pageSize": 20,
    "count": 1,
    "totalCount": 1
  }
}

오류 응답

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

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반함 파라미터 파싱 실패 Query 파라미터 표와 예시를 확인하세요.
500 ft.InternalServerError 조회, 주체 정보 보완 또는 응답 포맷팅 실패 내부 오류 traceId를 보관한 후 재시도하세요. 계속 실패하면 관리자에게 문의하세요.

문서 평가

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