콘텐츠로 이동

모든 레이블 조회



POST /api/v1/object/hosts/label/list

개요

데이터 소스 및 객체 이름 기준으로 인프라스트럭처 객체에 바인딩된 레이블 상세 정보를 읽습니다.

호출 전 준비 및 사용 단계

이 그룹의 레이블은 인프라스트럭처 객체에 바인딩된 레이블이며, 수집 Tag, 호스트 이름 또는 원시 로그 필드를 수정하는 것이 아니고, 전역 레이블 권한을 직접 관리하는 것과도 같지 않습니다. API Key는 현재 워크스페이스를 결정합니다. 이 페이지의 JSON Body에 따라 호출하세요. 이 레거시 라우트는 매개변수를 가져올 때 URL 매개변수로 JSON의 동일 이름 값을 덮어쓰거나 다른 필드를 보충하기도 합니다. URL에는 이 페이지 Body와 동일한 유효성 검사가 없으므로, 선언되지 않은 호환 필드를 안정적인 확장 계약으로 간주해서는 안 됩니다. URL 비즈니스 매개변수를 혼합하지 마세요.

routine.defaultAccess, infrastructure.setManage 또는 anonymous.snapshotShared 중 하나의 진입 권한이 필요하며, 실제 객체 조회는 데이터 액세스 규칙의 제약도 받습니다. source에는 실제 객체 분류를 입력하며, 호스트는 일반적으로 HOST입니다. names를 전달하지 않거나 []이면 해당 분류에서 반환되는 모든 객체를 조회하며, 이는 전체 워크스페이스의 모든 전역 레이블을 나열하는 것과 같지 않습니다. names로 소수의 객체를 먼저 필터링하여 검증할 수 있습니다. timeRange에는 두 개의 Unix 밀리초 시점을 명확히 지정하는 것이 좋습니다. 전달하지 않으면 업스트림에 빈 범위를 전달하며 모든 과거 데이터가 반환된다는 보장은 없습니다.

동적 객체 이름 매핑을 반환하며, 객체를 찾지 못한 경우 {}일 수 있습니다. 레이블 조회 및 객체 저장소에는 캐시가 있을 수 있으므로(과거 사용 설명에서는 일반적으로 약 5분) 수정 후에는 대기한 뒤 다시 읽어 확인해야 하며 강한 일관성을 요구할 수 없습니다. 원시 레이블 문자열은 현재 워크스페이스의 전역 레이블 정보와 매칭됩니다. 등록되지 않은 레이블은 빈 UUID의 임시 객체로 반환되며, 이번 읽기로 인해 자동으로 생성되지는 않습니다.

레이블 scope 정규화에서는 all, scene, monitor, dialing, security, infrastructure, catalog를 지원합니다. all은 다른 범위와 혼합할 수 없습니다. 레거시 레이블의 scope가 유효하지 않으면 조회에서도 406 invalid scope가 발생하므로 레이블 설정을 확인해야 하며, 이번 Body만 수정해서는 안 됩니다.

요청 헤더

매개변수명 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 이 작업 권한이 있는 OpenAPI Key를 획득합니다.

Body 요청 매개변수

매개변수명 유형 필수 설명
names array 선택적 배열이며, 생략하거나 []이면 이름으로 필터링하지 않습니다. 모든 요소를 중복 제거한 문자열로 구성하는 것이 좋습니다. 공개 배열에는 항목별 유형 검증이 없으므로 잘못된 요소는 비즈니스 단계에서 실패할 수 있습니다.
null 허용: False
예: ["host-example"]
획득 또는 입력 방법: 실제 객체 목록에서 객체 name을 복사하며 소스 분류와 일치해야 합니다.
source string Y 필수 문자열이며 데이터 도메인 namespace=object가 아닙니다. 소스 코드에는 HOST만 허용하는 열거 제약이 없습니다.
null 허용: False
예: HOST
획득 또는 입력 방법: 인프라스트럭처 페이지의 객체 분류 또는 실제 객체 수집 class에서 가져오며, 호스트는 보통 HOST를 사용합니다.
timeRange array 선택적 배열이며 두 개의 유효한 정수 밀리초를 권장합니다. 선언에는 길이/요소 유형 제한이 없으며, 생략하면 쿼리 서비스에 []를 전달합니다.
null 허용: False
예: [1785427200000, 1785429000000]
획득 또는 입력 방법: 조회할 객체의 시작/종료 Unix 밀리초 시간을 선택합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/object/hosts/label/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"source":"HOST","names":["host-example"],"timeRange":[1785427200000,1785429000000]}'

응답

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

필드 유형 설명
content.객체 이름 object 동적 객체 이름 키이며, 조회에서 반환된 tags.name에 해당합니다. 고정 host 필드가 아닙니다.
content.객체 이름.labels array 레이블 이름 기준으로 정렬된 레이블 정보 객체 목록이며 문자열 배열이 아닙니다.
content.객체 이름.labels[] object 하나의 레이블 정보입니다. 등록되지 않은 레이블도 임시 객체로 반환됩니다.
content.객체 이름.labels[].uuid string 전역 레이블 UUID입니다. 등록되지 않은 레이블은 빈 문자열이며 tag UUID 관리 인터페이스에 사용할 수 없습니다.
content.객체 이름.labels[].workspaceUUID string 등록된 레이블의 소속 워크스페이스입니다. 임시 객체는 비어 있습니다.
content.객체 이름.labels[].name string 레이블 이름입니다. 이후 labels를 수정할 때는 전체 객체나 uuid가 아니라 이 name 값을 제출해야 합니다.
content.객체 이름.labels[].description string 전역 레이블 설명입니다. 임시 객체는 비어 있습니다.
content.객체 이름.labels[].colour string 레이블 색상입니다. 임시 객체는 default입니다.
content.객체 이름.labels[].scope array 전역 레이블 적용 범위입니다. 임시 객체의 기본값은 [all]이며 현재 Key의 데이터 액세스 권한 부여가 아닙니다.
content.객체 이름.labels[].id integer 또는 string 등록된 레이블의 내부 행 번호입니다. 임시 객체는 빈 문자열이며 리소스 호출 매개변수로 사용하지 않습니다.
content.declaration object 또는 null 비어 있지 않은 결과의 최상위에만 추가되는 공용 워크스페이스 선언이며, 각 객체나 label에 재귀적으로 보충되지 않습니다.
{
  "code": 200,
  "content": {
    "host-example": {
      "labels": [
        {
          "uuid": "tag_example",
          "workspaceUUID": "wksp_example",
          "name": "production",
          "description": "生产环境",
          "colour": "default",
          "scope": [
            "all"
          ],
          "id": 10
        },
        {
          "uuid": "",
          "workspaceUUID": "",
          "name": "unmanaged-label",
          "description": "",
          "colour": "default",
          "scope": [
            "all"
          ],
          "id": ""
        }
      ]
    },
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

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

조회는 실제 데이터 권한과 쿼리 서비스에 따라 다른 구문/데이터 도메인 오류를 반환할 수 있습니다. HTTP와 오류 코드는 실제 응답 및 공통 설명에 따라 처리합니다. 여기서 설명하는 것은 현재 get_obj_labels이며, 다른 형태를 반환하는 내부 v2 메서드가 아닙니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 매개변수 파싱 실패 매개변수 위치, 필드 이름, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError Body가 JSON 객체가 아님 일부 JSON 파일 형식 오류 이 페이지의 JSON 객체를 제출합니다.
406 ft.DqlParseError 소스/이름으로 유효한 쿼리 표현식을 구성할 수 없음 dql parser 파싱 실패: {} 실제 소스와 객체 이름을 사용하고, 따옴표나 구문 제어 문자가 포함된 값을 수동으로 구성하지 않도록 하며, 먼저 쿼리를 확인합니다.
503 ft.QueryServiceUnavailable 객체 쿼리 업스트림 503이 정규화됨 쿼리 서비스를 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도하세요. content.retryable 안내에 따라 백오프 재시도하며, 고빈도 폴링은 하지 않습니다.
500 ft.InternalServerError 업스트림 구조, 배열 하위 요소/레이블 이름 유형 이상, 캐시/데이터베이스 오류 또는 비투과 서비스 5xx 내부 오류 객체 조회 범위를 축소하고 레거시 레이블 정보 및 업스트림 응답 구조를 확인합니다. 백오프 재시도하며, 지속적으로 실패하면 traceId를 제공합니다.
406 ft.ParameterValidationFailed 레거시 전역 레이블 scope가 빈 배열/알 수 없는 값 포함/all 혼합 등 잘못된 조합 invalid scope 관리자가 해당 전역 레이블의 scope를 수정하도록 하세요. 이러한 오류는 반드시 이번 조회 매개변수가 유효하지 않기 때문은 아닙니다.

문서 평가

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