콘텐츠로 이동

수정



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을 제출하십시오.

문서 평가

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