콘텐츠로 이동

생성



POST /api/v1/tag/create

개요

비즈니스 태그와 적용 범위를 생성합니다.

호출 전 확인 사항 및 사용 단계

대상 워크스페이스에서 먼저 이름이 이미 사용 중인지 확인하고, 적용 범위가 명확한 태그를 생성합니다. 이름은 대소문자를 구분하며, 서버 측 문자열 선언은 비어 있지 않은 값 검증을 보장하지 않으므로 호출자는 비어 있지 않은 비즈니스 이름을 입력해야 합니다. 기본값은 scope=["all"], colour=default, description은 빈 문자열입니다. 태그를 생성해도 어떤 리소스에도 자동으로 태그가 지정되지 않으며 리소스 권한도 부여되지 않습니다. 해당 리소스 API에서 태그 이름/UUID를 사용해 바인딩합니다.

요청 헤더

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

Body 요청 파라미터

파라미터명 타입 필수 설명
scope[*] string 배열의 멤버이며 all과 구체적인 값을 함께 사용하지 않습니다.
예: monitor
획득 또는 입력 방법: 상위 열거형에서 단일 범위를 선택합니다.
colour string 선택적 문자열입니다. 생성 시 기본값은 default이며, 수정 시 생략하면 기존 값을 유지하고 빈 문자열은 새 값으로 저장됩니다. 최대 50이며 계산 단위는 위와 같습니다. 서버는 색상 열거형을 고정하지 않으므로 고객 UI에서 지원하는 색상 표현을 선택해야 합니다.
null 허용: False
최대 길이: 50
예: default
획득 또는 입력 방법: 목록에 있는 기존 colour를 그대로 사용하거나 기본값 default를 사용할 수 있습니다.
description string 선택 사항입니다. 생성 시 생략하면 빈 문자열이며, 수정 시 생략하면 기존 값을 유지하고 명시적으로 빈 문자열을 입력하면 값을 지웁니다. 최대 100이며 계산 단위는 위와 같습니다.
null 허용: False
최대 길이: 100
예: 生产资源统一标记。
획득 또는 입력 방법: 비즈니스 담당자가 해당 태그의 용도를 설명합니다.
name string Y 생성 시 필수, 수정 시 선택 사항입니다. 비어 있지 않은 값을 권장하며, 최대 50 카운트 단위입니다(ASCII/반각 가타카나 1, 기타 문자 2). 이름은 대소문자를 구분하여 삭제되지 않은 중복을 판단하며 표시 이름을 UUID로 사용하지 않습니다. 콜론이 포함된 기존 태그는 허용되며, 본 공개 목록에서는 Front 일반/KV 디스패치를 수행하지 않습니다.
null 허용: False
최대 길이: 50
예: production
획득 또는 입력 방법: 비즈니스에서 사용자 지정한 태그 이름이며, 먼저 태그 목록에서 사용 중인 이름을 확인합니다.
scope any 비어 있지 않은 범위 배열이며, all 전역, scene 시나리오, monitor 모니터링, dialing 테스트, security 보안, infrastructure 인프라, catalog 통합 카탈로그를 열거합니다. 이전 단일 값 문자열과 호환됩니다. all은 다른 값과 함께 사용할 수 없으며, 중복 값은 제거되고 고정된 열거형 순서로 반환됩니다. []/null/알 수 없는 값은 허용되지 않습니다. 추가/가져오기 시 생략하면 기본값은 ["all"]이며, 수정 시 생략하면 기존 값을 유지합니다. scope는 태그의 적용 범위만 제한하며 리소스 권한을 부여하지 않습니다. 인프라/통합 카탈로그의 이름 바인딩은 여기에서 엔터티 참조를 정리해도 변경되지 않습니다.
null 허용: False
예: ["scene", "monitor"]
획득 또는 입력 방법: 태그를 바인딩할 리소스의 비즈니스 유형에 따라 선택합니다.

파라미터 추가 설명

데이터 설명

  • 요청 파라미터 설명
파라미터명 type 설명
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/create' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"production","description":"生产资源统一标记。","colour":"default","scope":["scene","monitor"]}'

응답

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> 정규화된 범위입니다. 기존 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.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": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "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를 제공하세요.

문서 평가

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