답글 생성¶
POST /api/v1/issue/reply/create
개요¶
Issue에 일반 답글을 생성하며, 업로드된 첨부 파일을 함께 바인딩하고 채널을 추가하며 멤버를 @할 수 있습니다.
호출 전 및 사용 단계¶
먼저 Issue 상세에서 대상 Issue를 확인합니다. issueUUID와 extend는 필수이며, 확장 내용이 없으면 {}를 전달합니다. 첨부 파일은 먼저 업로드하고, 답글 생성 시 attachmentUuids를 제출하여 바인딩합니다. extend.channels는 Issue에 이미 있는 채널에 추가 병합되며 이 답글에만 바인딩되지 않습니다. members는 이번 @ 알림에 사용됩니다. 성공하면 답글 uuid를 반환하며, 이후 답글 목록을 조회할 수 있습니다. API 성공이 알림 전달을 의미하지는 않습니다. 알림은 비동기로 실행되며, 수신자는 채널 구독, 알림 대상, 알림 정책, 담당자 및 이번 @ 멤버에 따라 결정됩니다. 콘솔에서 알림 설정과 실제 전달 여부를 확인하십시오. 쓰기와 이후 알림, 첨부 파일 처리는 단계별로 실행되므로, 실패하거나 타임아웃된 경우 먼저 리소스가 이미 생성 또는 업데이트되었는지 조회한 후 재시도 여부를 결정하여 중복 레코드와 알림을 방지하십시오.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 발급받습니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| attachmentUuids[*] | json | 업로드된 단일 첨부 파일 UUID입니다. 예시: att_example획득 또는 입력 방법: 첨부 파일 업로드의 content.attachmentUuid를 사용합니다. |
|
| extend.text | json | 선택 사항인 일반 텍스트로, 서버 측 길이 검사에 사용되며 최대 3000자입니다. 예시: 프로덕션 API 지연을 확인했습니다.획득 또는 입력 방법: 설명의 일반 텍스트에서 추출하여 3000자 이내로 작성합니다. 생략하면 빈 텍스트로 검사합니다. |
|
| extend.channels | array | 채널 참조 배열입니다. 이미 바인딩된 채널에 추가 병합되며, []는 기존 바인딩을 지우지 않습니다. 예시: [{"type": "#", "uuid": "chan_example", "name": "프로덕션 이상"}]획득 또는 입력 방법: 채널 목록에서 실제 채널 UUID를 가져와 설명의 # 채널을 참조합니다. 생략하면 추가하지 않습니다. |
|
| extend.channels[*] | json | 채널 참조 객체입니다. 예시: {"type": "#", "uuid": "chan_example", "name": "프로덕션 이상"}획득 또는 입력 방법: 각 항목에 동일 워크스페이스의 실제 채널 하나를 지정합니다. |
|
| extend.channels[*].uuid | json | 채널 UUID입니다. 예시: chan_example획득 또는 입력 방법: 채널 목록의 content[].uuid에서 가져옵니다. |
|
| extend.channels[*].name | json | 클라이언트 표시 이름입니다. 예시: 프로덕션 이상획득 또는 입력 방법: 채널 목록에서 해당 name을 가져와 표시에 사용하며 생략할 수 있습니다. |
|
| extend.channels[*].type | json | 채널 참조 표식입니다. 예시: #획득 또는 입력 방법: 채널 참조는 항상 #을 사용하며, 서버는 조회 결과에 이 표식을 보완합니다. |
|
| extend.channels[*].exists | json | 선택 사항인 표시 플래그로, 서버의 리소스 검증을 대체하지 않습니다. 예시: true획득 또는 입력 방법: 유효성 자격 증명으로 전달할 필요가 없으며, 조회 응답에서 현재 리소스 존재 여부에 따라 다시 계산됩니다. |
|
| extend.members | array | 이번 @ 멤버 참조로, 일회성 알림 이메일을 수집하는 데 사용됩니다. 담당자 배열이 아닙니다. 예시: [{"type": "@", "uuid": "acnt_example", "name": "온콜 엔지니어"}]획득 또는 입력 방법: 대상 워크스페이스의 멤버 관리에서 계정 UUID를 가져옵니다. 생략하면 이번 @ 멤버를 추가하지 않습니다. |
|
| extend.members[*] | json | 멤버 참조 객체입니다. 예시: {"type": "@", "uuid": "acnt_example", "name": "온콜 엔지니어"}획득 또는 입력 방법: @가 필요한 각 계정마다 객체를 작성합니다. |
|
| extend.members[*].uuid | json | 멤버 계정 UUID입니다. 예시: acnt_example획득 또는 입력 방법: 대상 워크스페이스의 멤버 관리에서 acnt_ 계정 UUID를 가져옵니다. |
|
| extend.members[*].name | json | 클라이언트 표시 이름입니다. 예시: 온콜 엔지니어획득 또는 입력 방법: 멤버 표시 이름을 사용하며 생략할 수 있습니다. |
|
| extend.members[*].type | json | 멤버 참조 표식입니다. 예시: @획득 또는 입력 방법: 멤버 참조에는 @를 사용합니다. |
|
| extend.members[*].exists | json | 선택 사항인 표시 플래그입니다. 예시: true획득 또는 입력 방법: 유효성 자격 증명으로 전달할 필요가 없으며, 조회 시 다시 계산됩니다. |
|
| extend.extra | json | 외부 표시 정보로, API의 실제 인증/작성자 신원을 대체하지 않습니다. 예시: {}획득 또는 입력 방법: 서드파티 연동에서 외부 작업자를 표시해야 할 때 작성하며, 없으면 생략하거나 {}를 전달합니다. |
|
| extend.extra.creator | json | 작성자 표시 객체입니다. 예시: {"name": "외부 티켓 작성자", "email": "xxx@guance.com"}획득 또는 입력 방법: 연동 시스템의 작성자 정보를 사용하며, 수정 시 기존 creator는 일반적으로 서버에서 유지됩니다. |
|
| extend.extra.creator.name | json | 표시 이름이며 생략할 수 있습니다. 예시: 외부 티켓 작성자획득 또는 입력 방법: 외부 시스템의 표시 이름을 사용합니다. |
|
| extend.extra.creator.email | json | 표시 이메일이며 생략할 수 있습니다. 예시: xxx@guance.com획득 또는 입력 방법: 외부 시스템의 이메일을 사용하며, 예시는 가상 주소입니다. |
|
| extend.extra.updator | json | 수정자 표시 객체입니다. 예시: {"name": "외부 티켓 수정자", "email": "xxx@guance.com"}획득 또는 입력 방법: 수정 시 연동 시스템의 이번 작업자 정보를 사용합니다. |
|
| extend.extra.updator.name | json | 표시 이름이며 생략할 수 있습니다. 예시: 외부 티켓 수정자획득 또는 입력 방법: 외부 시스템의 표시 이름을 사용합니다. |
|
| extend.extra.updator.email | json | 표시 이메일이며 생략할 수 있습니다. 예시: xxx@guance.com획득 또는 입력 방법: 외부 시스템의 이메일을 사용합니다. |
|
| attachmentUuids | array | 선택 사항인 업로드된 첨부 파일 UUID 배열로, 비어 있지 않으면 이 답글에 바인딩하거나 다시 바인딩합니다. 생략하거나 []이면 기존 첨부 파일을 삭제하지 않습니다. null 허용: True 예시: []획득 또는 입력 방법: 먼저 첨부 파일 업로드를 호출하고 content.attachmentUuid를 저장합니다. 해당 워크스페이스에서 실제로 업로드되어 사용 가능한 첨부 파일만 사용할 수 있습니다. 생략하거나 []이면 첨부 파일을 추가하지 않습니다. |
|
| content | string | 답글 내용입니다. 생성 시 최대 65535 길이 단위: ASCII 및 반각 가타카나는 문자당 1, 그 외 한자 등은 일반적으로 2로 계산하며, 공백 내용은 0으로 계산합니다. 생략하면 빈 문자열이 기본값입니다. 빈 문자열 허용: True null 허용: True $maxCustomLength: 65535 예시: 데이터베이스 슬로우 쿼리를 확인했으며 최적화 중입니다.획득 또는 입력 방법: 처리 진행 상황을 작성하며, 첨부 파일만 있는 답글은 생략하거나 빈 문자열을 전달할 수 있습니다. |
|
| extend | json | Y | 필수 확장 객체이며, 내용이 없으면 {}를 전달하고 null을 전달하지 마십시오. null 허용: True 예시: {}획득 또는 입력 방법: 확장 내용이 없으면 {}를 전달합니다. 수정 전에 원래 값을 먼저 읽고, 전체 객체에서 변경할 필드를 조정합니다. |
| issueUUID | string | Y | 답글이 속한 Issue UUID이며 필수입니다. null 허용: False 예시: issue_example획득 또는 입력 방법: Issue 목록 또는 Issue 상세에서 uuid를 가져옵니다. |
파라미터 추가 설명¶
이 API는 생성 전에 안정적인 "Issue가 존재하지 않음" 비즈니스 오류를 반환하지 않으므로, 대상 Issue가 존재하는지 먼저 확인하십시오. 유효한 내용이나 첨부 파일이 없는 빈 답글도 생성에 성공할 수 있으므로, 클라이언트는 비즈니스 요구 사항에 따라 검사해야 합니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/issue/reply/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"issueUUID":"issue_example","content":"데이터베이스 슬로우 쿼리를 확인했으며 최적화 중입니다.","extend":{}}'
응답¶
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.issueUUID | string | 소속 Issue UUID입니다. |
| content.content | string 또는 null | 답글 또는 작업 기록의 내용입니다. |
| content.type | string | reply는 일반 답글, change는 작업 기록, eventReply는 연관 이벤트 답글, autoDiscoveryReply는 자동 발견 답글입니다. |
| content.extend | object | 확장 내용입니다. 요청 시 객체 {}를 전달하고 null을 전달하지 마십시오. 멤버, 채널 및 담당자 등의 구조는 파라미터 표를 참조하십시오. |
| content.extend.text | string | 길이 검사에 사용되는 일반 텍스트이며 최대 3000자입니다. |
| content.extend.channels | array<object> |
설명에서 참조된 채널로 uuid, name, type, exists를 포함합니다. 반환 시 exists는 현재 리소스 존재 여부에 따라 갱신됩니다. |
| content.extend.channels[].uuid | string | 채널 UUID입니다. |
| content.extend.channels[].name | string 또는 null | 표시 이름입니다. |
| content.extend.channels[].type | string | 채널 참조 표식 #입니다. |
| content.extend.channels[].exists | boolean | 반환 시 해당 채널의 존재 여부입니다. |
| content.extend.members | array<object> |
설명에서 @된 멤버 참조로 uuid, name, type, exists를 포함합니다. |
| content.extend.members[].uuid | string | 멤버 계정 UUID입니다. |
| content.extend.members[].name | string 또는 null | 표시 이름입니다. |
| content.extend.members[].type | string | 멤버 참조 표식 @입니다. |
| content.extend.members[].exists | boolean | 반환 시 해당 계정의 존재 여부입니다. |
| content.extend.extra | object | 서드파티 연동 표시 정보이며 API의 실제 인증 신원을 변경하지 않습니다. |
| content.extend.extra.creator | object | 서드파티 작성자 표시 정보로, name, email을 포함할 수 있습니다. |
| content.extend.extra.creator.name | string | 작성자 표시 이름입니다. |
| content.extend.extra.creator.email | string | 작성자 표시 이메일입니다. |
| content.extend.extra.updator | object | 서드파티 수정자 표시 정보로, name, email을 포함할 수 있습니다. |
| content.extend.extra.updator.name | string | 수정자 표시 이름입니다. |
| content.extend.extra.updator.email | string | 수정자 표시 이메일입니다. |
| content.extend.extra.managerInfos | object | 담당자 이메일을 키로 하는 표시 정보 매핑이며 Issue에서만 사용합니다. |
| content.extend.extra.managerInfos.이메일.name | string | 해당 이메일 담당자의 표시 이름입니다. |
| content.extend.기타 필드 | JSON | 클라이언트가 저장한 기타 확장 정보입니다. 모두 비즈니스 동작을 트리거한다는 의미는 아닙니다. |
| content.declaration | object 또는 null | 워크스페이스 공통 선언이며 content의 이 계층에만 추가됩니다. |
{
"code": 200,
"content": {
"id": null,
"uuid": "repim_example",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"issueUUID": "issue_example",
"content": "데이터베이스 슬로우 쿼리를 확인했으며 최적화 중입니다.",
"type": "reply",
"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 파일 형식 오류 | JSON 객체를 제출하십시오. |
| 406 | ft.ExceedMaxLengthLimit | extend.text의 길이가 3000자를 초과함 | 텍스트 최대 길이 제한 초과 | 일반 텍스트 필드를 줄이고, 대량 진단 자료는 첨부 파일로 업로드하십시오. |
| 500 | ft.InternalServerError | 등급 또는 구성 저장, 감사 또는 기타 내부 처리 실패 | 내부 오류 | 현재 등급 또는 구성을 먼저 읽어 결과를 확인한 후 재시도 여부를 결정하고, 지속적으로 실패하면 traceId를 제공하십시오. |