수정¶
POST /api/v1/tag/{tag_uuid}/modify
개요¶
태그를 부분적으로 수정하고 새 scope에 따라 더 이상 적용되지 않는 참조를 정리합니다.
호출 전 및 사용 단계¶
부분 업데이트이며, 제출하지 않은 필드는 유지되고 빈 문자열은 명시적으로 덮어씁니다. 완전히 동일한 요청은 원본 엔터티를 반환하고 수정 감사 기록을 남기지 않습니다. scope가 변경되면 더 이상 허용되지 않는 리소스 참조와 모니터의 extend.incidentsTags에 있는 해당 태그 이름을 정리합니다. 이름/색상 변경은 문자열로 바인딩된 모든 외부 데이터를 대신 수정하지 않습니다.
현재 OpenAPI modify는 미리보기를 강제하지 않으며, scopePreviewToken을 생략하면 정리를 바로 실행할 수 있습니다. 먼저 scope_preview로 영향을 확인한 뒤 동일한 신원, 동일한 scope 및 반환된 token으로 제출하는 것이 좋습니다. token을 전달하면 600초 유효 기간과 전체 영향 지문을 검증하며, 리소스 관계/구성 변경이 있으면 다시 미리보기해야 합니다. 구성 변경이 더 이상 없는 no-op은 token을 검증하지 않습니다. scope, 이름 검증 및 참조 정리는 동일한 트랜잭션에서 수행되며, 실패하면 롤백됩니다. 제출 후 신서틱 테스트 작업 구성 동기화에 실패하면 pendingDialingTaskUUIDs에 표시됩니다. 태그는 이미 수정된 것이므로 전체 수정이 롤백된 것으로 간주하지 마십시오.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| tag_uuid | string | Y | 이 워크스페이스의 태그 UUID이며, 태그 이름, 목록의 숫자 페이지 번호 또는 리소스 UUID가 아닙니다. 예시: tag_example획득 또는 입력 방법: 태그 목록content.data[].uuid에서 가져옵니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 이 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| scope[*] | string | 배열 멤버이며 all과 구체적인 값을 혼용하지 않습니다. 예시: monitor획득 또는 입력 방법: 상위 열거형에서 단일 scope를 선택합니다. |
|
| colour | string | 선택적 문자열이며, 생성 시 기본값은 default입니다. 수정 시 생략하면 유지되고, 빈 문자열은 새 값으로 저장됩니다. 최대 50이며, 위와 동일한 카운트 단위를 적용합니다. 서버는 색상 열거형을 고정하지 않으므로 고객 인터페이스에서 지원하는 색상 표현을 선택해야 합니다. null 허용: False 최대 길이: 50 예시: default획득 또는 입력 방법: 목록에 이미 있는 colour를 그대로 사용하거나 기본값 default를 사용할 수 있습니다. |
|
| description | string | 선택 사항이며, 생성 시 생략하면 빈 문자열이고, 수정 시 생략하면 유지되며 명시적 빈 문자열은 지웁니다. 최대 100이며, 위와 동일한 카운트 단위를 적용합니다. null 허용: False 최대 길이: 100 예시: 生产资源统一标记。획득 또는 입력 방법: 비즈니스 담당자가 해당 태그의 용도를 설명합니다. |
|
| name | string | 생성 시 필수, 수정 시 선택 사항입니다. 비어 있지 않게 사용하는 것을 권장하며, 최대 50 카운트 단위입니다(ASCII/반각 가타카나 1, 기타 문자 2). 이름은 대소문자를 구분하여 삭제되지 않은 중복을 판단하며, 표시 이름을 UUID로 간주하지 않습니다. 콜론이 포함된 기존 태그는 허용하며, 이 공개 목록에서는 Front 일반/KV 분기를 수행하지 않습니다. null 허용: False 최대 길이: 50 예시: production획득 또는 입력 방법: 비즈니스에서 사용자 정의한 태그 이름이며, 먼저 태그 목록에서 이미 사용 중인 이름을 확인하십시오. |
|
| scope | any | 비어 있지 않은 scope 배열이며, 열거형은 all(전역), scene(시나리오), monitor(모니터링), dialing(신서틱 테스트), security(보안), infrastructure(인프라), catalog(통합 카탈로그)입니다. 이전 단일 값 문자열과 호환됩니다. all은 다른 값과 혼용할 수 없으며, 중복 값은 제거되고 고정된 열거형 순서로 반환됩니다. []/null/알 수 없는 값은 허용되지 않습니다. 생성/가져오기 시 생략하면 기본값은 ["all"]이고, 수정 시 생략하면 기존 값을 유지합니다. scope는 태그 적용 범위만 제한하며 리소스 권한을 부여하지 않습니다. 인프라/통합 카탈로그의 이름 바인딩은 여기서의 엔터티 참조 정리에 따라 변경되지 않습니다. null 허용: False 예시: ["scene", "monitor"]획득 또는 입력 방법: 태그를 바인딩할 리소스의 비즈니스 유형에 따라 선택합니다. |
|
| scopePreviewToken | string | 선택 사항이며, 수정 시 실제로 scope가 변경될 때만 검증에 참여합니다. 최대 128자입니다. 유효 기간은 600초이며, 호출 신원/워크스페이스/태그/새 scope 및 현재 영향 범위에 바인딩됩니다. 변경되거나 만료되면 다시 미리보기해야 합니다. 현재 공개 modify에서는 생략하면 정리 및 수정을 바로 수행할 수 있으며 사전 확인을 강제하지 않습니다. 전달하면 유효성을 검사하며, 이전 token으로 재시도하지 마십시오. null 허용: False 예시: PREVIEW-TOKEN획득 또는 입력 방법: 이 태그의 scope 미리보기content.previewToken에서 가져옵니다. |
파라미터 추가 설명¶
데이터 설명
- 요청 파라미터 설명
| 파라미터 이름 | 유형 | 설명 |
|---|---|---|
| name | string | 태그 이름 |
| description | string | 필드 설명 정보 |
| color | string | 프런트엔드와 백엔드에서 합의한 색상 유형, default,style_key1,style_key2 ~~ |
- 색상 color 필드의 유형별 색상 대응표:
{ "default": {"background": "#CCE6FF", "color": "rgba(0,0,0,0.8)"}, "style_key1": {"background": "#3333FE", "color": "#FFFFFF"}, "style_key2": {"background": "#428BCA", "color": "#FFFFFF"}, "style_key3": {"background": "#364450", "color": "#FFFFFF"}, "style_key4": {"background": "#E0E1FF", "color": "rgba(0,0,0,0.8)"}, "style_key5": {"background": "#9400D3", "color": "#FFFFFF"}, "style_key6": {"background": "#EDDBFF", "color": "rgba(0,0,0,0.8)"}, "style_key7": {"background": "#CC328B", "color": "#FFF"}, "style_key8": {"background": "#FCDEF0", "color": "rgba(0,0,0,0.8)"}, "style_key9": {"background": "#DC143D", "color": "#FFFFFF"}, "style_key10": {"background": "#FCBABA", "color": "rgba(0,0,0,0.8)"}, "style_key11": {"background": "#BD0B48", "color": "#FFFFFF"}, "style_key12": {"background": "#FDECD2", "color": "rgba(0,0,0,0.8)"}, "style_key13": {"background": "#FFC29C", "color": "rgba(0,0,0,0.8)"}, "style_key14": {"background": "#ED9120", "color": "#FFFFFF"}, "style_key15": {"background": "#CD5B44", "color": "#FFFFFF"}, "style_key16": {"background": "#FAF570", "color": "rgba(0,0,0,0.8)"}, "style_key17": {"background": "#C29953", "color": "#FFFFFF"}, "style_key18": {"background": "#02B140", "color": "#FFFFFF"}, "style_key19": {"background": "#D5F4D5", "color": "rgba(0,0,0,0.8)"}, "style_key20": {"background": "#009966", "color": "#FFFFFF"}, "style_key21": {"background": "#023220", "color": "#FFFFFF"}, "style_key22": {"background": "#E7E7E7", "color": "rgba(0,0,0,0.8)"}, "style_key23": {"background": "#808080", "color": "#FFFFFF"} }
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/tag/tag_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"description":"生产资源标记已更新。"}'
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer | 엔터티 레코드 번호입니다. 목록 id는 UUID 문자열이며, 목록 필드를 참조하십시오. |
| content.uuid | string | tag_태그 UUID입니다. |
| content.workspaceUUID | string | 소속 워크스페이스입니다. |
| content.name | string | 태그 이름입니다. |
| content.description | string | 용도 설명입니다. |
| content.colour | string | 색상 표현입니다. |
| content.scope | array<string> |
정규화된 scope이며, 과거 null/빈 scope는 ["all"]로 반환됩니다. |
| content.scope[] | string | all/scene/monitor/dialing/security/infrastructure/catalog 중 하나입니다. |
| content.status | integer | 0은 유효, 3은 삭제이며, 기타 이전 상태는 실제 데이터를 따릅니다. |
| content.creator | string | 생성 신원입니다. |
| content.updator | string | 최근 수정 신원입니다. |
| content.createAt | integer | 생성 시각(Unix 초)입니다. |
| content.updateAt | integer | 업데이트 시각(Unix 초)이며, 업데이트되지 않은 경우 -1입니다. |
| content.deleteAt | integer | 삭제 시각(Unix 초)이며, 삭제되지 않은 경우 -1입니다. |
| content.affectedRelationCount | integer | 실제 scope 변경 시 정리된 엔터티 참조 수이며, 생략될 수 있습니다. |
| content.affectedConfigCount | integer | 실제 scope 변경 시 incidentsTags에서 정리된 모니터 규칙 구성 수이며, 생략될 수 있습니다. |
| content.pendingDialingTaskUUIDs | array<string> |
태그는 제출되었지만 신서틱 테스트 구성 새로고침에 실패한 작업 UUID이며, 생략될 수 있습니다. |
| content.pendingDialingTaskUUIDs[] | string | 관리자가 확인하고 재시도하여 다시 배포해야 하는 작업 UUID입니다. |
| content.declaration | object | 공통 선언입니다. |
{
"code": 200,
"content": {
"id": 100,
"uuid": "tag_example",
"workspaceUUID": "wksp_example",
"name": "production",
"description": "生产资源标记已更新。",
"colour": "default",
"scope": [
"scene",
"monitor"
],
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427300,
"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을 수정하십시오. |
| 406 | ft.TagNameExists | 이 워크스페이스에 동일한 이름의 삭제되지 않은 태그가 존재함 | 동일한 이름의 태그가 이미 존재함 | 이름을 변경하거나 먼저 기존 태그를 확인하십시오. |
| 500 | ft.InternalServerError | 데이터베이스, 태그/권한 구조, 캐시 또는 응답 포맷팅에 실패함 | 내부 오류 | 요청을 확인한 뒤 태그의 현재 상태를 다시 읽으십시오. 쓰기가 이미 커밋되었을 수 있으므로 무작정 반복하지 마십시오. 계속 실패하면 traceId를 제공하십시오. |
| 404 | ft.ObjectNotExists | 이 워크스페이스에 해당하는 유효한 태그가 없거나 이미 삭제됨 | 지정한 객체가 존재하지 않음 | 현재 워크스페이스 목록에서 유효한 UUID를 가져오십시오. |
| 400 | ft.TagScopeConfirmationRequired | scope 변경 시 빈/누락된 자격 증명이 전달되었고 해당 경로에서 확인이 필요한 경우(예: 명시적 빈 token이 확인 검사를 트리거함) | 영향을 받는 리소스를 먼저 확인하십시오 | 먼저 미리보기하고 반환된 token으로 제출하십시오. 이 공개 엔트리에서는 token을 완전히 생략하면 바로 수정할 수 있으므로 영향을 직접 확인해야 합니다. |
| 400 | ft.TagScopePreviewExpired | scope가 실제로 변경되었고 전달된 token이 만료되었거나 신원/범위/현재 영향 지문과 일치하지 않음 | 영향 범위가 변경되었으므로 다시 미리보기하여 확인하십시오 | 동일한 scope를 다시 미리보기한 뒤 새 token을 제출하십시오. |