콘텐츠로 이동

인시던트 댓글 생성



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 데이터베이스, 캐시/큐, 유효하지 않은 첨부 파일, 확장되지 않은 하위 필드 유형/기존 비정상 구조 또는 다운스트림 미처리 예외 내부 오류 읽기 요청은 백오프 후 재시도할 수 있습니다. 쓰기 요청은 먼저 인시던트/댓글 현재 상태 및 알림 기록을 읽으십시오. 이미 제출되었을 수 있으므로 중복 생성 또는 중복 알림을 피하십시오.

문서 평가

이 페이지가 도움이 되었나요?