생성¶
POST /api/v1/channel/add
개요¶
인시던트 채널을 생성하고 알림 대상 및 에스컬레이션 알림을 구성합니다.
호출 전 준비 및 사용 단계¶
먼저 채널 간략 목록에서 이름을 확인하며, 생성 시 최소한 name만 있으면 됩니다. 이름은 default를 사용하지 않아야 합니다. 알림을 보내야 하는 경우 실제 알림 대상 UUID를 먼저 준비해야 합니다. 예시는 채널만 생성하며, 알림을 구성할 때는 매개변수 표에 따라 전체 필드를 별도로 제출합니다. 채널과 에스컬레이션 트리거 구성은 단계별로 저장됩니다. 시간 초과 또는 오류 발생 후에는 먼저 채널 상태를 조회한 다음 재시도할 필드를 결정하여 중복 생성을 방지합니다. 에스컬레이션 알림은 규칙을 활성화하거나 업데이트한 후 새로 생성되었고 아직 종료되지 않았으며 담당자가 없는 Issue를 대상으로 합니다. triggerTime을 초과하면 예약 작업에서 확인하며, 정확한 카운트다운은 아닙니다. 현재 작업은 또한 워크스페이스에 유효한 담당자 없음 에스컬레이션 알림 정책이 있어야 합니다. 메시지를 받지 못한 경우 알림 정책, 알림 대상 및 사이트 작업 스위치를 확인하세요.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| notifyTarget[*] | string | 단일 알림 대상 UUID입니다. 예시: notify_example가져오기 또는 입력 방법: 알림 대상 목록을 사용하여 동일한 워크스페이스에 구성된 알림 대상을 조회하고 content.data[].uuid를 가져옵니다. |
|
| notifyUpgradeCfg.notifyTarget[*] | string | 단일 에스컬레이션 알림 대상 UUID입니다. 예시: notify_example가져오기 또는 입력 방법: 알림 대상 목록을 사용하여 동일한 워크스페이스에 구성된 알림 대상을 조회하고 content.data[].uuid를 가져옵니다. |
|
| description | string | 채널 설명이며 최대 256자입니다. 빈 문자열 허용: True null 허용: False 최대 길이: 256 예시: 生产异常协作频道가져오기 또는 입력 방법: 채널 용도에 따라 입력하며, 빈 문자열을 전달하면 지울 수 있습니다. |
|
| name | string | Y | 채널 이름이며 최대 256자입니다. null 허용: False 최대 길이: 256 예시: 生产异常가져오기 또는 입력 방법: 채널 간략 목록에서 기존 이름을 확인한 다음, 이 워크스페이스에서 사용되지 않은 이름을 선택합니다. |
| notifyTarget | array | 전체 알림 대상 UUID 배열이며, []를 전달하면 구성을 비웁니다. null 허용: False 예시: ["notify_example"]가져오기 또는 입력 방법: 알림 대상 목록을 사용하여 동일한 워크스페이스에 구성된 알림 대상을 조회하고 content.data[].uuid를 가져옵니다. |
|
| notifyUpgradeCfg | json | 전체 에스컬레이션 알림 구성입니다. 이 객체를 전달하는 경우 triggerTime과 notifyTarget을 동시에 제공해야 합니다. null 허용: False 예시: {"triggerTime": 300, "notifyTarget": ["notify_example"]}가져오기 또는 입력 방법: 비즈니스 대기 시간에 따라 초를 선택하고 실제 알림 대상 UUID를 사용합니다. |
|
| notifyUpgradeCfg.notifyTarget | array | 조건부 필수 | 전체 에스컬레이션 알림 대상 UUID 목록입니다. triggerTime=0과 조합하여 비활성화합니다. null 허용: False 예시: ["notify_example"]가져오기 또는 입력 방법: 알림 대상 목록을 사용하여 동일한 워크스페이스에 구성된 알림 대상을 조회하고 content.data[].uuid를 가져옵니다. |
| notifyUpgradeCfg.triggerTime | integer | 조건부 필수 | 에스컬레이션 알림을 기다리는 시간(초)입니다. 0이 아닌 경우 규칙을 활성화하려면 알림 대상이 하나 이상 있어야 합니다. null 허용: False 예시: 300가져오기 또는 입력 방법: 양의 정수(초)를 입력합니다. 예를 들어 300은 5분 대기를 의미합니다. 비활성화 시에는 빈 notifyTarget 배열과 함께 0을 전달합니다. |
매개변수 추가 설명¶
notifyUpgradeCfg는 0이 아닌 triggerTime과 비어 있지 않은 notifyTarget을 동시에 제공해야만 에스컬레이션 트리거 구성이 생성됩니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/channel/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产异常","description":"生产异常协作频道"}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 데이터베이스 레코드 번호입니다. 생성 시 영속화 전에 응답을 구성하므로 null일 수 있습니다. 리소스 작업에는 uuid를 사용하세요. |
| content.uuid | string | 채널 UUID로, 수정, 삭제 또는 구독에 사용됩니다. |
| content.workspaceUUID | string | 채널이 속한 워크스페이스입니다. |
| content.name | string | 채널 이름입니다. default는 기본 채널을 의미합니다. |
| content.description | string | 채널 설명입니다. |
| content.notifyTarget | array<string> |
이 채널에 직접 구성된 알림 대상 UUID입니다. |
| content.notifyTarget[] | string | 단일 알림 대상 UUID입니다. |
| content.notifyUpgradeCfg | object | 에스컬레이션 알림 구성이며, 구성되지 않은 경우 빈 객체입니다. |
| content.notifyUpgradeCfg.triggerTime | integer | 에스컬레이션 알림을 트리거하는 대기 시간(초)입니다. |
| content.notifyUpgradeCfg.notifyTarget | array<string> |
에스컬레이션 알림 대상 UUID 목록입니다. |
| content.notifyUpgradeCfg.notifyTarget[] | string | 에스컬레이션 알림 대상 UUID입니다. |
| content.status | integer | 레코드 상태이며 정상일 때 0입니다. |
| content.creator | string | 생성 호출 주체입니다. |
| content.updator | string | 최근 업데이트 주체이며, 업데이트되지 않은 경우 빈 문자열일 수 있습니다. |
| content.createAt | integer | 생성 시간, Unix 초입니다. |
| content.updateAt | integer | 업데이트 시간, Unix 초이며 업데이트되지 않은 경우 -1입니다. |
| content.deleteAt | integer | 삭제 시간, Unix 초이며 삭제되지 않은 경우 -1입니다. |
| content.declaration | object 또는 null | 워크스페이스의 공통 선언입니다. |
{
"code": 200,
"content": {
"id": null,
"uuid": "chan_example",
"workspaceUUID": "wksp_example",
"name": "生产异常",
"description": "生产异常协作频道",
"notifyTarget": [],
"notifyUpgradeCfg": {},
"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을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 단일 JSON 객체를 전달합니다. |
| 400 | ft.ChannelNameRepeat | 동일한 이름의 채널이 존재하거나 동일한 이름의 동시 생성이 처리 중임 | 채널 이름 중복 | 먼저 현재 채널 목록을 확인합니다. 동시 생성 시 잠시 기다린 후 재시도가 필요한지 확인합니다. |
| 400 | ft.InvalidChannelName | 생성 시 name이 default임 | 채널 이름으로 default 사용 금지 | 사용자 정의 채널 이름으로 변경합니다. |