사용자 정의 레벨 추가¶
POST /api/v1/issue-level/add
개요¶
현재 워크스페이스에 사용자 정의 Issue 레벨을 생성합니다.
호출 전 및 사용 단계¶
이름과 색상만 제출하면 되며, description, extend는 생략할 수 있습니다. 이 워크스페이스에서 삭제되지 않은 사용자 정의 레벨은 최대 10개입니다. 이름은 이 워크스페이스에 이미 존재하는 삭제되지 않은 사용자 정의 레벨과 중복될 수 없습니다. 성공하면 issl_로 시작하는 uuid를 반환합니다. 플랫폼 전역 레벨이 우선 적용되는 경우, 새로 생성한 레벨이 저장되었더라도 당분간 유효 레벨 목록에 나타나지 않을 수 있습니다. Issue에 사용할 수 있는지는 유효 목록을 기준으로 결정합니다. 작업은 현재 API Key가 속한 워크스페이스를 사용합니다. 동일한 워크스페이스에서 리소스 식별자를 가져오세요. 타임아웃 발생 시 먼저 콘솔의 레벨 설정에서 생성 여부를 확인한 후 재시도 여부를 결정하세요.
요청 헤더¶
| 매개변수名 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수名 | 유형 | 필수 | 설명 |
|---|---|---|---|
| extend.사용자 정의 필드 | json | 임의의 추가 JSON 필드입니다. 예: urgent가져오기 또는 입력 방법: 통합 시스템이 비즈니스 요구에 따라 이름을 지정하고 필드 유형을 안정적으로 유지합니다. |
|
| color | string | Y | 레벨 색상으로, 생성 시 필수입니다. 서버에서는 문자열로 선언하며 색상 형식 열거형은 제한하지 않습니다. null 허용: False 예: #FF7931가져오기 또는 입력 방법: 클라이언트에서 표시할 수 있는 색상을 선택하고 #RRGGBB 문자열 사용을 권장합니다. |
| description | string | 선택적 레벨 설명입니다. null 허용: False 예: 需要当天响应가져오기 또는 입력 방법: 판정 기준과 기대 응답 시간을 간략히 설명하며 1024자를 초과하지 않도록 권장합니다. 생략하면 빈 문자열이 됩니다. |
|
| extend | json | 선택적 추가 JSON으로, 생성 시 저장됩니다. 고정된 비즈니스 하위 필드는 없습니다. null 허용: True 예: {}가져오기 또는 입력 방법: 사용자 정의 추가 정보를 저장해야 할 때 JSON 객체를 전달합니다. 내용이 없으면 생략하거나 {}를 사용합니다. |
|
| name | string | Y | 레벨 이름으로, 생성 시 필수입니다. 최대 256자로 선언되어 있으나 현재 영속화 필드는 더 짧으므로 128자 이내로 유지할 것을 권장합니다. null 허용: False 최대 길이: 256 예: 紧急处理가져오기 또는 입력 방법: 비즈니스에 따라 이 워크스페이스에서 사용되지 않은 이름을 선택하고 128자를 초과하지 않도록 권장합니다. |
매개변수 추가 설명¶
사용자 정의 레벨 생성은 기존 Issue의 level을 변경하지 않으며, Issue 알림을 직접 전송하지도 않습니다. 현재 라우트의 이름 256자 선언과 영속화 용량 간에는 차이가 있으므로, 권장 길이를 사용하면 저장 실패를 줄일 수 있습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/issue-level/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"紧急处理","color":"#FF7931","description":"需要当天响应"}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 레코드 번호입니다. Issue/답글 생성 응답이 영속화 전에 구성되는 경우 null일 수 있으므로 리소스 작업에는 uuid를 사용하세요. |
| content.uuid | string | 리소스 UUID입니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID입니다. |
| content.status | integer | 레코드 상태입니다. 0 정상, 3 삭제됨입니다. Issue 비즈니스 상태 statusType과 구분합니다. |
| content.creator | string | 생성 호출 주체로, API Key 식별자, 계정 또는 시스템 주체일 수 있습니다. |
| content.updator | string | 최근 업데이트 주체입니다. 설정되지 않은 경우 빈 문자열입니다. |
| content.createAt | integer | 생성 시간(Unix 초)입니다. |
| content.updateAt | integer | 최근 업데이트 시간(Unix 초)입니다. 업데이트되지 않은 경우 -1일 수 있습니다. |
| content.deleteAt | integer | 삭제 시간(Unix 초)입니다. 삭제되지 않은 경우 -1입니다. |
| content.name | string | 사용자 정의 레벨 이름입니다. |
| content.color | string | 색상 문자열입니다. |
| content.description | string | 레벨 설명입니다. |
| content.extend | object 또는 null | 생성 시 저장된 추가 JSON 객체입니다. 레벨 수정 API는 현재 이 필드를 수정하지 않습니다. |
| content.isManage | boolean 또는 number | 플랫폼 관리 레벨인지 여부입니다. 워크스페이스에서 직접 생성한 경우 일반적으로 false입니다. |
| content.declaration | object 또는 null | 워크스페이스 공용 선언입니다. content의 이 계층에만 추가됩니다. |
{
"code": 200,
"content": {
"id": 201,
"uuid": "issl_example",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"name": "紧急处理",
"description": "需要当天响应",
"color": "#FF7931",
"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 파일 형식 오류 | JSON 객체를 제출하세요. |
| 406 | ft.IssueLevelCountLimit | 이 워크스페이스에 삭제되지 않은 사용자 정의 레벨이 10개 있음 | 워크스페이스 사용자 정의 레벨이 워크스페이스 허용 최대 수량인 10개를 초과함 | 더 이상 사용하지 않는 사용자 정의 레벨을 정리한 후 재시도하세요. |
| 406 | ft.IssueLevelNameExists | 이 워크스페이스에 동일한 이름의 삭제되지 않은 사용자 정의 레벨이 있음 | 레벨 이름이 이미 존재함 | 다른 이름을 선택하세요. 타임아웃 후에는 먼저 생성 여부를 확인하세요. |
| 500 | ft.InternalServerError | 레벨 또는 구성 저장, 감사 또는 기타 내부 처리 실패 | 내부 오류 | 먼저 현재 레벨 또는 구성을 읽어 결과를 확인한 후 재시도 여부를 결정하세요. 지속적으로 실패하면 traceId를 제공하세요. |