모든 레이블 조회¶
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를 수정하도록 하세요. 이러한 오류는 반드시 이번 조회 매개변수가 유효하지 않기 때문은 아닙니다. |