댓글 수정¶
POST /api/v1/incidents/comment/{comment_uuid}/modify
개요¶
직접 생성한 인시던트 댓글을 수정합니다.
호출 전 및 사용 단계¶
현재 Key에는 incidents.incidentsReplyManage 권한이 필요하며 현재 워크스페이스에만 적용됩니다. 경로 comment_uuid는 댓글 목록의 content.data[].uuid에서 가져옵니다. 원래 생성 주체만 수정할 수 있으며, 다른 Key는 역할이 같더라도 거부됩니다. 동일 Key를 교체하더라도 리소스 UUID는 유지됩니다. comment는 항상 필수입니다. extend는 생략하면 유지되고, 포함되면 전체가 교체됩니다. 기존 extra.creator/managerInfos가 존재하면 호환 규칙에 따라 유지되며, 표시 필드를 통해 작성자를 변조할 수 없습니다. 수정 시 현재 새로 추가된 @멤버 이메일은 발송되지 않으므로, members 필드 저장 성공만으로 알림이 전송되었다고 판단해서는 안 됩니다.
첨부 파일 UUID는 이 모듈의 업로드를 통해 획득합니다. 이번 바인딩은 추가/재바인딩이며, 생략하거나 []를 사용해도 바인딩이 해제되지 않습니다. 기존 첨부 파일은 첨부 파일 삭제에서 별도로 작업해야 합니다. 댓글/첨부 파일/알림은 단계별로 제출되며, 500/타임아웃이 발생해도 댓글이나 첨부 파일이 저장되었을 수 있습니다. 먼저 페이지네이션으로 다시 읽어 본문, 생성 주체, 시간을 기준으로 확인하여 중복 댓글과 알림을 피하십시오. 댓글 생성에는 멱등 키가 없으며, 수정을 반복 제출해도 업데이트 시간이 변경됩니다. 응답에는 현재 첨부 파일 요약이 포함됩니다. creatorInfo/updatorInfo는 반환되지 않으므로 댓글 목록에서 보완해야 합니다.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| comment_uuid | string | Y | 단일 댓글 UUID이며 인시던트 UUID가 아닙니다. null 허용: False 예시: inccmt_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 | 기존 보조 신원입니다. 수정 시 기존 creator가 우선하며 실제 댓글 생성 Key 신원을 덮어쓸 수 없습니다. 예시: {}가져오기 또는 입력 방법: 기존 extra.creator 자료입니다. |
|
| extend.extra.managerInfos | object | 이메일에서 신원 객체로의 매핑입니다. 유효한 새 매핑을 제공하지 않으면 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/inccmt_example/modify' \
-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 | 외부 신원 보조 자료입니다. 수정 시 원래 creator와 manager에 여전히 남아 있는 managerInfos를 유지할 수 있습니다. |
| content.extend.extra.creator | JSON | 원래 생성 측 보조 신원 자료입니다. 기존 값이 있으면 수정 시 이를 통해 생성자를 덮어쓸 수 없습니다. |
| content.extend.extra.managerInfos | object | 기존 담당자 이메일에서 신원 자료로의 동적 매핑입니다. |
| content.extend.extra.managerInfos.이메일 | JSON | 해당 이메일에 대응하는 원래 신원 자료입니다. |
| 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.attachments | array<object> |
연결된 첨부 파일 요약이며 연결되지 않은 경우 []입니다. |
| content.attachments[].uuid | string | 첨부 파일 UUID입니다. 이 모듈의 downloadAttachment API를 통해 다운로드합니다. |
| content.attachments[].fileName | string | 원본 파일 이름입니다. |
| content.attachments[].fileSuffix | string | 파일 확장자이며 점(.)은 포함하지 않습니다. 파일 내용/직접 링크는 반환하지 않습니다. |
| content.declaration | object | 현재 워크스페이스의 공개 선언입니다. |
{
"code": 200,
"content": {
"id": 123,
"uuid": "inccmt_example",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"incidentsUUID": "incident_example",
"workspaceUUID": "wksp_example",
"comment": "데이터베이스 연결 이상이 확인되어 처리 중입니다.",
"extend": {},
"attachments": [],
"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 파일 형식 오류 | 객체를 제출하십시오. |
| 404 | ft.ObjectNotExists | 현재 워크스페이스에서 해당 활성 댓글을 찾을 수 없습니다 | 지정된 객체가 존재하지 않습니다 | 이 워크스페이스의 댓글 목록에서 uuid를 다시 획득하십시오. |
| 400 | ft.IssueReplyNotModify | 현재 Key 리소스 UUID가 원래 댓글 creator와 일치하지 않습니다 | 해당 답글의 생성자가 아니므로 편집이 허용되지 않습니다 | 원래 생성 Key를 사용하십시오. extend를 통해 작성자를 수정하여 권한을 우회하지 마십시오. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시/큐, 유효하지 않은 첨부 파일, 확장되지 않은 하위 필드 유형/기존 예외 구조 또는 다운스트림 미처리 예외 | 내부 오류 | 읽기 요청은 백오프 후 재시도할 수 있습니다. 쓰기 요청은 먼저 인시던트/댓글 현재 상태 및 알림 기록을 읽으십시오. 이미 커밋되었을 수 있으므로 중복 생성이나 중복 알림을 피하십시오. |