인시던트 댓글 생성¶
POST /api/v1/incidents/comment/{incident_uuid}/add
개요¶
지정한 인시던트에 댓글을 추가하고 비동기로 알림을 전송합니다.
호출 전 및 사용 단계¶
현재 Key에는 incidents.incidentsReplyManage 권한이 필요하며 현재 워크스페이스에서만 사용할 수 있습니다. 경로의 incident_uuid는 먼저 인시던트 상세를 사용해 현재 워크스페이스에 대상이 존재하고 삭제되지 않았음을 확인해야 합니다. 이 엔드포인트는 먼저 댓글을 저장한 뒤 인시던트를 조회하고 비동기 알림을 전송합니다. 유효하지 않은 인시던트 UUID에 대해 사전 존재 여부 거부를 보장하지 않으며, 고아 댓글이 먼저 생성된 뒤 500이 발생할 수 있습니다. 따라서 이 엔드포인트로 인시던트 존재 여부를 검증해서는 안 됩니다. 댓글 생성 시 인시던트에 담당자가 이미 있으면 알림 후보는 담당자와 유효한 @ 이메일이며, 담당자가 없으면 유효한 @ 이메일만 사용합니다. 둘 다 없으면 전송하지 않을 수 있습니다. reply는 현재 일치하는 일정에 따른 대체 알림으로 자동 전환되지 않습니다. 비동기 채널/음소거 등의 조건은 실제 전달에 여전히 영향을 미치며, 성공 응답만으로 도달을 보장할 수 없습니다.
첨부 파일 UUID는 본 모듈의 업로드를 통해 가져옵니다. 이번 바인딩은 추가/재바인딩이며, 생략하거나 []를 사용해도 바인딩이 해제되지 않습니다. 기존 첨부 파일은 첨부 파일 삭제로 별도 작업해야 합니다. 댓글/첨부 파일/알림은 단계별로 제출됩니다. 500/시간 초과가 발생해도 댓글이나 첨부 파일이 저장되었을 수 있습니다. 먼저 페이지 단위로 다시 읽어 본문, 생성 주체, 시간을 기준으로 확인하여 중복 댓글과 알림을 피하십시오. 댓글 생성에는 멱등 키가 없으며, 수정을 반복 제출해도 업데이트 시간이 변경됩니다. 응답에는 댓글 엔터티와 공통 선언만 포함되며 방금 바인딩한 첨부 파일 요약은 포함되지 않습니다. 첨부 파일과 ID 정보는 댓글 목록에서 읽습니다.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| incident_uuid | string | Y | 현재 워크스페이스 인시던트 UUID이며 알림 이벤트 ID, SLO UUID 또는 댓글 UUID가 아닙니다. null 허용: False 예시: incident_example가져오기 또는 입력 방법: 인시던트 목록에서 content.data[].uuid를 가져옵니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| attachmentUUIDs[*] | string | 단일 첨부 파일 UUID 문자열입니다. 예시: att_example가져오기 또는 입력 방법: 먼저 첨부 파일 업로드에서 content.attachmentUuid를 가져오고 첨부 파일 소유권을 확인합니다. |
|
| extend.members | array | 선택적 계정 멘션 배열입니다. 댓글 생성 시 type=@이고 uuid가 있는 계정 이메일을 필터링하고 중복을 제거합니다. 계정 조회는 워크스페이스 기준으로 다시 제한하지 않으므로 호출자는 확인된 현재 워크스페이스 멤버를 사용해야 합니다. 알림 전달은 보장되지 않습니다. 수정 시 후보를 계산하지만 현재 해당 이메일 알림은 전송하지 않습니다. 예시: [{"type": "@", "uuid": "acnt_example", "exists": true}]가져오기 또는 입력 방법: 현재 워크스페이스 멤버 목록에서 계정 UUID를 가져온 뒤 편집기 멘션에 맞게 구성합니다. |
|
| extend.members[*] | object | 하나의 멘션 객체이며 임의의 이메일로 uuid를 대체할 수 없습니다. 예시: {"type": "@", "uuid": "acnt_example", "exists": true}가져오기 또는 입력 방법: members와 동일한 출처를 사용합니다. |
|
| extend.members[*].type | string | @만 추가 이메일 후보에 포함되며 다른 유형은 포함되지 않습니다. 예시: @가져오기 또는 입력 방법: 편집기 계정 멘션 표시입니다. |
|
| extend.members[*].uuid | string | 삭제되지 않은 계정 UUID입니다. 대응하는 계정이 없으면 이메일 후보에 포함되지 않습니다. 예시: acnt_example가져오기 또는 입력 방법: 현재 워크스페이스 멤버 목록의 계정 UUID입니다. |
|
| extend.members[*].exists | boolean | 선택적 호환 플래그이며 현재 알림 로직은 이 값을 존재 여부 판정에 사용하지 않습니다. 예시: true가져오기 또는 입력 방법: 호출자 편집기에서 멤버 존재 상태에 따라 입력합니다. |
|
| extend.linkList | array | 표시용 링크 배열이며 본 API가 대상에 접근하거나 검증하지 않습니다. 예시: [{"name": "문제 해결 매뉴얼", "link": "https://example.com/runbook"}]가져오기 또는 입력 방법: 관련 문서 링크를 입력합니다. |
|
| extend.linkList[*] | object | 하나의 링크 객체입니다. 예시: {"name": "문제 해결 매뉴얼", "link": "https://example.com/runbook"}가져오기 또는 입력 방법: linkList와 동일한 출처를 사용합니다. |
|
| extend.linkList[*].name | string | 문자열 표시 이름입니다. 예시: 문제 해결 매뉴얼가져오기 또는 입력 방법: 링크 표시 이름을 입력합니다. |
|
| extend.linkList[*].link | string | URL 문자열입니다. 예시: https://example.com/runbook가져오기 또는 입력 방법: 고객이 접근할 수 있는 주소를 입력합니다. |
|
| extend.manager | array | 기존 외부 담당자 이메일 배열이며 이전 managerInfos 호환성 유지를 위해서만 사용되고 인시던트 담당자 설정을 대체하지 않습니다. 예시: ["xxx@guance.com"]가져오기 또는 입력 방법: 기존 댓글에 현재 있는 extend.manager이며 수정 전에 원래 값을 읽습니다. |
|
| extend.manager[*] | string | 단일 기존 이메일입니다. 예시: xxx@guance.com가져오기 또는 입력 방법: 기존 manager 배열입니다. |
|
| extend.extra | object | 선택적 객체입니다. 기존 creator가 있으면 덮어쓰지 않도록 이전 값을 복사합니다. 비밀번호/토큰을 이 공개 확장에 넣지 마십시오. 예시: {}가져오기 또는 입력 방법: 기존 댓글에 현재 있는 extra 보조 정보입니다. |
|
| extend.extra.creator | object | 기존 보조 ID이며, 수정 시 기존 creator가 우선하고 실제 댓글 생성 Key 주체를 덮어쓸 수 없습니다. 예시: {}가져오기 또는 입력 방법: 기존 extra.creator 정보입니다. |
|
| extend.extra.managerInfos | object | 이메일에서 ID 객체로의 매핑입니다. 유효한 새 매핑이 제공되지 않으면 manager 배열에 여전히 나타나는 이전 항목만 유지됩니다. 예시: {}가져오기 또는 입력 방법: 기존 extra.managerInfos 매핑입니다. |
|
| attachmentUUIDs | array | 생략하면 바인딩하지 않습니다. 제공되면 각각을 댓글에 추가/재바인딩하며 []는 기존 첨부 파일을 지우지 않습니다. 유효하지 않거나 삭제된 UUID는 500이 발생할 수 있고, 바인딩 내부에서 제출되므로 이후 실패해도 이미 저장되었을 수 있습니다. 직접 확인한 유효한 첨부 파일만 사용하고 다른 리소스의 첨부 파일을 빌려 사용하지 마십시오. null 허용: False 예시: ["att_example"]가져오기 또는 입력 방법: 먼저 첨부 파일 업로드에서 content.attachmentUuid를 가져오고 첨부 파일 소유권을 확인합니다. |
|
| comment | string | Y | 필수 문자열입니다. 현재 선언에서는 비어 있지 않음을 강제하지 않지만 의미 있는 내용을 제공하는 것이 좋으며 빈 문자열을 삭제 대신 사용하지 마십시오. null 허용: False 예시: 데이터베이스 연결 이상을 확인했으며 처리 중입니다.가져오기 또는 입력 방법: 현재 담당자가 인시던트 진행 상황을 입력합니다. |
| extend | json | JSON 객체여야 합니다. 생성 시 생략하면 {}이고, 수정 시 생략하면 유지되며, 제공되면 전체가 교체됩니다({}는 비우지만 기존 extra.creator/managerInfos는 호환성을 위해 유지됩니다). 루트 파라미터가 null/배열/문자열이면 공개 라우트에서 먼저 406으로 거부합니다. 내부 members:null, 객체가 아닌 멤버 또는 extra:null 등 선언되지 않은 하위 구조는 500이 발생할 수 있으므로 본문의 하위 필드 구조에 따라 입력해야 합니다. null 허용: False 예시: {"members": [{"type": "@", "uuid": "acnt_example", "exists": true}], "linkList": [{"name": "문제 해결 매뉴얼", "link": "https://example.com/runbook"}]}가져오기 또는 입력 방법: 호출자 편집기에서 구성하며 표시해야 할 멘션과 링크를 유지합니다. |
파라미터 추가 설명¶
첨부 파일은 먼저 본 모듈의 attachmentUpload를 통해 업로드한 다음 content.attachmentUuid를 attachmentUUIDs에 전달합니다. extend.members는 계정 UUID로 멘션합니다. 댓글을 추가하면 알림이 발송되지만, 댓글을 수정할 때 현재 해당 멘션 알림을 다시 보내지는 않습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/incidents/comment/incident_example/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"comment":"데이터베이스 연결 이상을 확인했으며 처리 중입니다."}'
응답¶
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.incidentsUUID | string | 소속 인시던트 UUID입니다. |
| content.workspaceUUID | string | 소속 워크스페이스입니다. |
| content.comment | string | 댓글 본문이며 시스템 생성 작업 설명을 포함할 수 있습니다. 본문을 구조화된 작업 기록으로 간주하지 마십시오. |
| content.extend | object 또는 JSON | 저장된 확장이며 시스템 댓글은 operator/operator_info/operate_type/before/after 등을 포함할 수 있습니다. |
| content.extend.members | array<object> |
@멤버 입력 기록으로, 댓글 생성 시 추가 이메일 알림 후보에 사용되며 전달 완료를 의미하지 않습니다. |
| content.extend.members[].type | string | @는 계정 멘션을 의미하며 다른 값은 해당 이메일 후보에 포함되지 않습니다. |
| content.extend.members[].uuid | string | 계정 UUID입니다. |
| content.extend.members[].exists | boolean | 고객 편집기 상태이며 서버 알림 필터링은 이 값에 의존하지 않습니다. |
| content.extend.linkList | array<object> |
비즈니스 링크 표시 정보입니다. |
| content.extend.linkList[].name | string | 링크 표시 이름입니다. |
| content.extend.linkList[].link | string | 링크 URL입니다. |
| content.extend.manager | array<string> |
기존 외부 담당자 이메일 배열이며 수정 시 기존 extra.managerInfos를 유지할 때 필터링에 사용됩니다. 인시던트 assigner와 동일하지 않습니다. |
| content.extend.manager[] | string | 하나의 기존 담당자 이메일입니다. |
| content.extend.extra | object | 외부 ID 보조 정보이며 수정 시 기존 creator와 manager에 여전히 있는 managerInfos를 유지할 수 있습니다. |
| content.extend.extra.creator | JSON | 원 생성자 보조 ID 정보이며 기존 값이 있으면 수정으로 생성자를 덮어쓸 수 없습니다. |
| content.extend.extra.managerInfos | object | 기존 담당자 이메일에서 ID 정보로의 동적 매핑입니다. |
| content.extend.extra.managerInfos.邮箱 | JSON | 해당 이메일에 대응하는 원래 ID 정보입니다. |
| content.extend.operator | string | 시스템 작업 댓글의 원래 작업 주체 식별자입니다. |
| content.extend.operator_info | object | 시스템 작업 댓글에 첨부된 주체 요약입니다. |
| content.extend.operate_type | string | 시스템 작업 댓글에 첨부된 작업 유형입니다. |
| content.extend.before | JSON | 시스템 작업의 이전 값이며 작업에 따라 달라집니다. |
| content.extend.after | JSON | 시스템 작업의 새 값이며 작업에 따라 달라집니다. |
| content.extend.自定义字段 | JSON | 호출자/시스템이 저장한 기타 확장 키-값이며 본 API는 고정 구조를 보장하지 않습니다. |
| content.extend.operator_info.uuid | string | 주체 UUID이며 시스템 응답 주체는 비어 있거나 시스템 식별자일 수 있습니다. |
| content.extend.operator_info.status | integer | 주체 상태입니다. |
| content.extend.operator_info.wsAccountStatus | integer | 워크스페이스 멤버 상태이며 Key는 Key 상태를 가져오고 인시던트 상태가 아닙니다. |
| content.extend.operator_info.username | string | 로그인 이름/Key 이름/시스템 이름입니다. |
| content.extend.operator_info.name | string | 표시 이름이며 시스템 AI 표시 이름은 사이트 설정을 사용합니다. |
| content.extend.operator_info.iconUrl | string | 아바타 URL이며 시스템 요약에서는 생략될 수 있습니다. |
| content.extend.operator_info.email | string | 연락 이메일이며 Key 요약은 Key UUID일 수 있고 전달 가능한 이메일이 아닙니다. |
| content.extend.operator_info.mobile | string | 연락 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.extend.operator_info.countryCode | string | 국가 코드이며 시스템 요약에서는 생략될 수 있습니다. |
| content.extend.operator_info.acntWsNickname | string | 워크스페이스 닉네임이며 시스템 요약에서는 생략될 수 있습니다. |
| content.declaration | object | 현재 워크스페이스 공통 선언입니다. |
{
"code": 200,
"content": {
"id": 123,
"uuid": "inccmt_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"incidentsUUID": "incident_example",
"workspaceUUID": "wksp_example",
"comment": "데이터베이스 연결 이상을 확인했으며 처리 중입니다.",
"extend": {},
"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 파일 형식 오류 | 객체를 제출합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시/큐, 유효하지 않은 첨부 파일, 확장되지 않은 하위 필드 유형/기존 비정상 구조 또는 다운스트림 미처리 예외 | 내부 오류 | 읽기 요청은 백오프 후 재시도할 수 있습니다. 쓰기 요청은 먼저 인시던트/댓글 현재 상태 및 알림 기록을 읽으십시오. 이미 제출되었을 수 있으므로 중복 생성 또는 중복 알림을 피하십시오. |