생성¶
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를 제공하세요. |