커스텀 등급 추가¶
POST /api/v1/incidents/level/add
개요¶
현재 워크스페이스의 커스텀 인시던트 등급을 생성합니다.
호출 전 및 사용 단계¶
Key에는 incidents.incidentsLevelManage 권한이 필요하며, 현재 Key가 속한 워크스페이스에만 적용됩니다. 이 모듈은 Issue 등급 API와 하위 등급 및 기본 등급 구성을 공유하므로, 변경 시 인시던트/Issue 등급 선택에 동시에 영향을 줄 수 있습니다. 본 모듈에서만 독립된 복사본을 만드는 것은 아닙니다. 백그라운드에서 전역 등급을 활성화한 경우 실제 유효한 등급 선택은 전역 구성이 우선 결정할 수 있으며, 본 워크스페이스의 관리 목록에는 여전히 기본 등급과 워크스페이스 커스텀 항목만 나열되고 백그라운드 전역 등급은 포함되지 않습니다. 관리자가 적용 기준을 확인한 후 수정하고, 관리 목록의 모든 항목을 사용 가능한 등급으로 간주하지 마십시오.
본 워크스페이스에서 삭제되지 않은 커스텀 등급은 최대 10개이며, 이름 기준으로 중복을 검사합니다. 기본 등급 4개는 포함되지 않습니다. 생성 시 issl_등급UUID가 반환되어 인시던트 level 등의 파라미터에서 참조할 수 있습니다. 멱등 키는 존재하지 않으므로 타임아웃/500 발생 시 먼저 이름으로 조회하고 중복 생성하지 않습니다. 등급 구성만 생성하며 기존 인시던트를 수정하거나 인시던트 알림을 트리거하지 않습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| color | string | Y | 생성 시 필수, 수정 시 생략 가능합니다. 문자열만 선언하며 색상 형식은 검증하지 않고, 데이터베이스 128자이므로 유효한 16진수 색상 사용을 권장합니다. null 허용: False 예시: #3F94DC획득 또는 입력 방법: 고객 UI 배색에 맞춰 입력하며 #RRGGBB를 권장합니다. |
| description | string | 선택 문자열입니다. 생성 시 생략하면 빈 문자열, 수정 시 생략하면 유지, 빈 문자열이면 초기화되며 null은 허용하지 않습니다. 데이터베이스 1024자이므로 호출자가 제한해야 합니다. null 허용: False 예시: 局部功能受影响획득 또는 입력 방법: 비즈니스 담당자가 등급 판정 기준을 작성합니다. |
|
| extend | json | 생성 시 객체 또는 null만 허용하며, 생략하면 기본값은 {}입니다. 배열/문자열 등은 먼저 선언 검증에서 406으로 거부됩니다. 수정 라우트에 선언되어 있더라도 검증을 통과한 객체 또는 null은 컨트롤러에서 무시되므로 기존 extend가 변경되지 않으며 {}로 초기화할 수 없습니다. null 허용: True 예시: {}획득 또는 입력 방법: 생성 시 저장이 필요한 JSON 비즈니스 확장을 입력합니다. |
|
| name | string | Y | 생성 시 필수, 수정 시 생략 가능합니다. 동일 워크스페이스의 활성 커스텀 등급은 이름이 중복될 수 없습니다. 선언상 최대 256자, 데이터베이스 128자이므로 1~128자를 권장하며, 현재 비어 있지 않음을 강제하지는 않습니다. null 허용: False 최대 길이: 256 예시: P3-轻微획득 또는 입력 방법: 비즈니스 심각도에 따라 식별하기 쉬운 이름을 정합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/incidents/level/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"P3-轻微","color":"#3F94DC","description":"局部功能受影响"}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 데이터베이스 행 ID입니다. 비즈니스 식별에는 uuid를 사용하며, 제출 전 스냅샷은 null일 수 있습니다. |
| content.uuid | string | 해당 리소스 UUID입니다. |
| content.status | integer | 데이터베이스 상태로 0은 활성/3은 삭제입니다. 인시던트 비즈니스 상태인 incidentsStatus와 다릅니다. |
| content.creator | string | 생성 주체이며, API Key는 일반적으로 wsak_리소스UUID입니다. |
| content.updator | string | 최근 업데이트 주체이며, 업데이트가 없으면 비어 있을 수 있습니다. |
| content.createAt | integer | Unix 초 단위 생성 시간입니다. |
| content.updateAt | integer | Unix 초 단위 최근 업데이트 시간입니다. |
| content.deleteAt | integer | Unix 초 단위 삭제 시간이며, 삭제되지 않았으면 -1입니다. |
| content.workspaceUUID | string | 등급이 속한 워크스페이스입니다. |
| content.name | string | 커스텀 등급 이름입니다. |
| content.color | string | 색상 표시 값으로 일반적으로 #RRGGBB이며, 서버 측에서 색상 형식을 검증한다고 보장하지 않습니다. |
| content.description | string | 등급 설명입니다. |
| content.extend | JSON 또는 null | 생성 시 저장된 확장으로 생략하면 {}이며, 명시적 null도 저장할 수 있습니다. 수정 진입점에서는 현재 이 필드를 무시합니다. |
| content.extend.사용자 정의 필드 | JSON | 호출자가 저장한 동적 비즈니스 확장이며, 추가 제어 파라미터가 아닙니다. |
| content.isManage | boolean | 본 워크스페이스에서 생성된 경우 false이며, 백그라운드 전역 등급은 본 모듈에서 수정하지 않습니다. |
| content.declaration | object | 현재 워크스페이스의 공통 선언입니다. |
{
"code": 200,
"content": {
"id": 123,
"uuid": "issl_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"name": "P3-轻微",
"color": "#3F94DC",
"description": "局部功能受影响",
"extend": {},
"isManage": false,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 객체를 제출합니다. |
| 406 | ft.IssueLevelCountLimit | 본 워크스페이스의 미삭제 커스텀 등급이 이미 10개 | 워크스페이스 커스텀 등급이 워크스페이스 허용 최대 개수 10개를 초과했습니다 | 먼저 유지할 등급을 확인하고, 참조 마이그레이션을 계획한 후 불필요한 항목을 삭제합니다. |
| 406 | ft.IssueLevelNameExists | 동일 워크스페이스의 활성 커스텀 등급이 이미 해당 이름을 사용 | 등급 이름이 이미 존재합니다 | 먼저 기존 등급을 조회하고, 구성을 변경해야 하면 원래 uuid를 수정합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 구성/ID 형식 또는 처리되지 않은 시스템 예외 | 내부 오류 | 읽기는 백오프 후 재시도할 수 있습니다. 쓰기는 먼저 구성/등급 목록을 다시 읽어 저장 여부를 확인한 후 재시도 여부를 결정합니다. |