첨부 파일 업로드¶
POST /api/v1/attachment/upload
개요¶
워크스페이스의 첨부 파일을 업로드하고 첨부 파일 식별자를 반환하며, 이후 Issue 또는 인시던트 코멘트 연결에 사용합니다. 이 API는 파일만 업로드하며 코멘트를 자동으로 생성하지 않습니다.
호출 전 및 사용 단계¶
- 첨부할 로컬 파일과 첨부 파일 업로드 권한이 있는 워크스페이스 API Key를 준비합니다. 요청은 multipart/form-data이며 필드 이름은 files입니다.
- 업로드 성공 후 content.attachmentUuid를 저장한 다음, 인시던트 코멘트 추가의 요청 배열 attachmentUUIDs에 해당 식별자를 입력합니다. 업로드 자체로는 코멘트가 추가되지 않습니다.
- 한 번에 하나의 파일만 업로드하며 최대 50 MiB입니다. 요청 시간이 초과되면 먼저 첨부 파일이 생성되었는지 확인한 후 재전송 여부를 결정합니다.
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | AK 식별자, AK uuid 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 본 API 권한을 가진 Key를 생성하거나 획득합니다. |
파일 파라미터(multipart/form-data)¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| files | file | Y | 첨부 파일 단일 파일 크기 상한: 50M 파일 수 상한: 1 허용 파일 확장자: ['txt', 'json', 'mp4', 'mov', 'png', 'jpg', 'pdf', 'xls', 'xlsx'] 예시: @/path/to/image.png획득 또는 입력 방법: 업로드할 로컬 파일 경로를 입력하며, curl에서는 -F를 사용하고 경로 앞에 @를 붙입니다. |
파라미터 추가 설명¶
multipart/form-data를 사용하여 실제 파일 바이너리를 업로드합니다. 파일 필드 이름은 반드시files여야 하며, 한 번에 하나의 파일만 업로드합니다.- 파일 part에는 파일 이름이 포함되어야 합니다. 예:
Content-Disposition: form-data; name="files"; filename="image.png". - 요청 헤더에
DF-API-KEY를 제공합니다. curl의-F또는 HTTP 클라이언트의 multipart builder를 사용하여 Content-Type과 boundary를 자동 생성합니다. - 단일 파일 크기는 50 MiB(50 × 1024 × 1024 바이트)를 초과할 수 없으며, 허용 파일 확장자는 파일 파라미터 표와 같고 확장자 검증은 대소문자를 구분하지 않습니다.
- Lark
imageKey는 파일로 직접 업로드할 수 없습니다. 먼저 이미지 바이너리를 획득한 후.png또는.jpg확장자가 붙은 파일 이름으로 업로드해야 합니다. files파일이 없거나,file필드를 잘못 사용하거나, 파일 이름을 제공하지 않으면 HTTP 406을 반환하며errorCode는ft.ParameterValidationFailed입니다. 파일 확장자, 크기 및 수가 요구 사항을 충족하지 않을 때도 거부됩니다.
성공 응답의 content 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
| fileName | string | 업로드 시의 원본 파일 이름 |
| attachmentUuid | string | 첨부 파일 식별자로, 이후 API에서 첨부 파일을 연결하는 데 사용합니다. 필드 이름의 대소문자에 주의하세요 |
| fileSuffix | string | 원본 파일 이름의 확장자 |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/attachment/upload' \
--header 'DF-API-KEY: <DF-API-KEY>' \
--form 'files=@/path/to/image.png'
응답¶
HTTP 200, application/json. 업로드 성공 시 첨부 파일 메타데이터를 반환합니다. 성공 업로드가 반복되면 새로운 첨부 파일 식별자가 생성될 수 있습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.fileName | string | 업로드 시의 원본 파일 이름입니다. |
| content.attachmentUuid | string | 첨부 파일 식별자로, 인시던트 코멘트 추가 요청의 attachmentUUIDs 배열에 사용됩니다. |
| content.fileSuffix | string | 서버에 기록된 파일 확장자입니다. |
{
"code": 200,
"content": {
"fileName": "image.png",
"attachmentUuid": "att_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"fileSuffix": "png"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE_ID"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | files 누락, 필드 이름 오류, 파일 수 초과, 지원하지 않는 확장자 또는 파일 크기 초과 | 메시지에 누락된 필드 또는 위반된 규칙(예: fileSuffix 또는 limitSize)이 표시됩니다. | files 필드에 지원되는 50 MiB 이하의 파일 하나를 업로드합니다. |