콘텐츠로 이동

첨부 파일 업로드



POST /api/v1/attachment/upload

개요

워크스페이스의 첨부 파일을 업로드하고 첨부 파일 식별자를 반환하며, 이후 Issue 또는 인시던트 코멘트 연결에 사용합니다. 이 API는 파일만 업로드하며 코멘트를 자동으로 생성하지 않습니다.

호출 전 및 사용 단계

  1. 첨부할 로컬 파일과 첨부 파일 업로드 권한이 있는 워크스페이스 API Key를 준비합니다. 요청은 multipart/form-data이며 필드 이름은 files입니다.
  2. 업로드 성공 후 content.attachmentUuid를 저장한 다음, 인시던트 코멘트 추가의 요청 배열 attachmentUUIDs에 해당 식별자를 입력합니다. 업로드 자체로는 코멘트가 추가되지 않습니다.
  3. 한 번에 하나의 파일만 업로드하며 최대 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 이하의 파일 하나를 업로드합니다.

문서 평가

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