호스트 label 수정¶
POST /api/v1/object/hosts/{host}/label/modify
개요¶
지정된 인프라스트럭처 객체의 label 집합을 전체 교체하며, 생략하거나 빈 배열을 전달하면 비웁니다.
호출 전 및 사용 단계¶
이 label 집합은 인프라스트럭처 객체에 바인딩된 label이며, 수집 Tag, 호스트 이름 또는 원시 로그 필드를 수정하는 것이 아니고, 글로벌 label 권한을 직접 관리하는 것과도 같지 않습니다. API Key가 현재 워크스페이스를 결정합니다. 이 페이지의 JSON Body에 따라 호출하십시오. 이 레거시 라우트의 매개변수 처리에서는 URL 매개변수로 JSON의 동일 이름 값을 덮어쓰거나 다른 필드를 보충할 수도 있으며, URL에는 이 페이지 Body와 동일한 검증이 없으므로 선언되지 않은 호환 필드를 안정적인 확장 계약으로 삼아서는 안 됩니다. URL 비즈니스 매개변수를 함께 전달하지 마십시오.
infrastructure.setManage 권한이 필요합니다. host는 현재 source 아래의 객체 name이며, 라우트 경로에는 한 번에 하나의 단일 세그먼트 이름만 지정할 수 있습니다. 객체 UUID 또는 글로벌 Tag UUID를 전달할 수 없으며, 이름에 포함된 슬래시는 인코딩하더라도 이 경로와 일치하지 않을 수 있습니다. source는 객체 분류와 일치해야 합니다. 먼저 모든 label 가져오기를 통해 현재 집합을 읽고, 유지할 label.name을 보존한 다음, 목표 전체 문자열 배열을 제출하십시오. 증분 추가가 아닙니다.
labels를 생략하거나 []를 전달하면 모두 전체 label을 비우는 호출이 되며, 생략으로 '원래 값 유지'를 표현할 수 없습니다. 비어 있지 않은 집합은 먼저 객체 조회 서비스에 기록한 뒤, 아직 등록되지 않은 이름에 대해 글로벌 label 레코드를 생성합니다. 이 두 단계는 서비스 간 원자적 트랜잭션이 아니므로, 마지막 단계가 실패해도 객체 label은 이미 적용되었을 수 있습니다. 중복되거나 유효하지 않은 이름은 데이터베이스 오류를 일으킬 수 있으므로 실제 이름을 기준으로 중복을 제거하고 글로벌 label 명명 규칙을 준수하십시오. 비우기는 해당 객체 바인딩만 해제하며 글로벌 label 레코드를 삭제하지 않습니다.
성공 시 항상 true를 반환하며, 영향을 받은 수나 최종 객체를 제공하지 않습니다. 존재하지 않는 객체에 대해 404를 반환한다고 보장하지 않고, 캐시가 새로 고쳐졌다는 것도 증명하지 않습니다. 업스트림의 특정 쓰기 오류 삭제는 SDK에서 무시되며, 결과를 알 수 없을 때는 다시 읽어 확인해야 하고, true만으로 실제 변경을 증명할 수 없습니다.
라우트 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| host | string | Y | 실제 URL 경로 매개변수입니다. Body 또는 URL 매개변수의 name으로 이 경로 값을 대체하지 않습니다. 예시: host-example가져오기 또는 입력 방법: 현재 source의 객체 목록에서 name을 복사하며, 한 번에 하나의 단일 세그먼트 이름을 사용합니다. |
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| labels | array | 선택적 문자열 요소 배열로, 최종 전체 집합을 나타냅니다. 생략하거나 []를 전달하면 비웁니다. label 상세 객체 또는 uuid를 제출할 수 없습니다. 배열 요소에는 재귀 검증이 선언되어 있지 않으며, 유효하지 않은 값에 대해 사전 406을 보장하지 않습니다. null 허용: False 예시: ["production", "service-api"]가져오기 또는 입력 방법: 모든 label 가져오기 응답의 content[객체 name].labels[].name에서 label 이름을 가져옵니다. 객체 name은 경로 host 및 Body source와 대응해야 하며, label uuid를 사용하지 마십시오. |
|
| source | string | Y | 필수 문자열이며, 경로에 hosts가 포함되어 있다는 이유만으로 생략하거나 모든 source를 기본값으로 사용할 수 없습니다. null 허용: False 예시: HOST가져오기 또는 입력 방법: 객체와 일치하는 실제 객체 분류를 사용합니다(예: 호스트 HOST). |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/object/hosts/host-example/label/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"source":"HOST","labels":["production","service-api"]}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 성공 시 항상 true입니다. 객체/label 상세가 아니며, 강한 일관성 또는 영향을 받은 건수를 의미하지 않습니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
수정 호출은 업스트림 label 쓰기 인터페이스를 호출하므로 오류가 업스트림 상태에 따라 달라질 수 있습니다. 일반적인 5xx는 최종적으로 500으로 래핑됩니다. 로컬에서 호스트를 조회할 수 없다고 해서 객체 없음 404를 항상 반환하지는 않으며, 멱등성과 강한 일관성을 가정할 수 없습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 매개변수 파싱 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | 요청 Body가 JSON 객체가 아님 | 일부 json 파일 형식 오류 | source 및 대상 labels 배열을 제출하십시오. |
| 500 | ft.InternalServerError | label 요소/저장 오류 또는 업스트림의 비전달 5xx | 내부 오류 | 먼저 객체의 현재 label을 읽어 어느 단계까지 실행되었는지 판단한 후 재시도 여부를 결정하고, traceId를 제공하십시오. |