업로드
재개 가능한 업로드: 업로드 세션을 만들고, 바이트를 한 번에 또는 파트로 나누어 보내고, 완료한 후 완료 작업을 추적합니다.
이 그룹의 작업과 각 작업의 액세스 규칙, 재시도 규칙, 매개 변수, 응답입니다. 모든 요청에는 키가 포함됩니다: Authorization: Bearer <키>(“인증” 참조).
작업
업로드된 파트 목록
GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts
액세스: 리포지토리 권한: upload.read; 파일 키: write · 재시도: 반복해도 안전함(읽기)
업로드를 만들 때 정해진 파트 크기 partBytes(8 MiB이며, 10,000개를 넘는 파트가 필요한 파일은 크기를 두 배로 늘립니다. 마지막 파트만 더 짧습니다)와, 이미 저장된 파트의 인덱스, 크기, SHA-256을 반환합니다. 중단된 멀티파트 업로드를 재개하기 전에 읽고, 빠진 파트만 putUploadPart로 보냅니다. 업로드를 만든 사용자만 볼 수 있으며 그 외에는 404입니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
partBytes | integer | 아니요 | 8388608–1073741824; 마지막 파트를 제외한 모든 파트가 이 크기입니다. |
items | object 배열 | 아니요 | — |
items[].index | integer | 예 | 0–9999 |
items[].size | integer | 예 | 1–1073741824 |
items[].sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"파트 하나 업로드
PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}
액세스: 리포지토리 권한: upload.write; 파일 키: write · 재시도: 업로드를 다시 읽은 후 결정
요청 본문을 보류 중인 멀티파트 업로드의 index번 파트(0부터 시작)로 저장합니다. 본문 길이는 정확히 partBytes(listUploadParts에서 확인)여야 하며 마지막 파트는 남은 길이여야 합니다. X-Content-SHA256 헤더는 이 바이트의 소문자 16진수 SHA-256이어야 하며, 그렇지 않으면 422입니다. 파트는 어떤 순서로 도착해도 되지만 한 업로드는 한 번에 요청 하나만 받습니다(동시 요청은 503 busy). 같은 해시로 파트를 다시 보내는 것은 안전하며, 이미 저장된 인덱스에 다른 해시를 보내면 409 part_mismatch입니다. 모든 파트가 저장되면 completeUpload 또는 enqueueCompletion을 호출합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
index | 경로 | integer | 예 | 0–9999 |
X-Content-SHA256 | 헤더 | string | 예 | SHA-256: 소문자 16진수 64자리 |
요청 본문 (application/octet-stream)
응답: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts/$INDEX" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "X-Content-SHA256: $X_CONTENT_SHA256" \
-H "Content-Type: application/octet-stream" \
--data-binary @file백그라운드에서 업로드 완료
POST /api/v1/repositories/{repository}/uploads/{id}/complete-async
액세스: 리포지토리 권한: upload.complete; 파일 키: write · 재시도: 작업을 다시 읽은 후 결정
요청 안에서 처리하는 대신 보류 중인 업로드의 완료를 워커 서비스용 큐에 넣고, 즉시 202와 함께 작업을 반환합니다. 진행 상황은 getCompletionJob으로 확인합니다. 같은 업로드에 다시 호출하면 같은 작업을 반환하며, 일시적인 이유로 실패한 작업은 다시 큐에 들어갑니다. 작업이 큐에 있다는 것은 아티팩트가 게시되었다는 뜻이 아니며, completed일 때만 게시된 것입니다. 업로드가 더 이상 보류 상태가 아니면 409 upload_state, 호출자의 열린 작업이 100개이거나 서버 전체가 10,000개이면 507 queue_full입니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 202
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
uploadId | string (uuid) | 예 | — |
repository | string | 예 | — |
owner | string | 예 | — |
status | string | 예 | queued, running, completed, failed 중 하나 |
generation | integer | 예 | 0–2147483647 |
attempts | integer | 예 | 0 이상 |
credentialId | string (uuid) | 아니요 | 작업을 시작한 관리형 키의 ID(선택 사항). 비밀 값은 포함하지 않습니다. |
errorCode | string | 예 | null일 수 있음 |
응답: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
-H "Authorization: Bearer $ARKVORY_TOKEN"완료 작업 조회
GET HEAD /api/v1/jobs/{id}
액세스: 리포지토리 권한: job.read; 파일 키: write · 재시도: 반복해도 안전함(읽기)
enqueueCompletion으로 큐에 넣은 완료 작업의 상태를 반환합니다. 상태는 queued, running, completed(업로드가 게시됨), 또는 errorCode를 포함한 failed이며, 시도 횟수도 함께 제공합니다. 워커는 간격을 점점 늘려 가며 최대 다섯 번 시도하고, integrity_mismatch 같은 오류는 즉시 실패합니다. 작업을 만든 사용자만 볼 수 있으며 그 외에는 404입니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
uploadId | string (uuid) | 예 | — |
repository | string | 예 | — |
owner | string | 예 | — |
status | string | 예 | queued, running, completed, failed 중 하나 |
generation | integer | 예 | 0–2147483647 |
attempts | integer | 예 | 0 이상 |
credentialId | string (uuid) | 아니요 | 작업을 시작한 관리형 키의 ID(선택 사항). 비밀 값은 포함하지 않습니다. |
errorCode | string | 예 | null일 수 있음 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"업로드 세션 생성
POST /api/v1/repositories/{repository}/uploads
액세스: 리포지토리 권한: upload.create; 파일 키: write · 재시도: 같은 Idempotency-Key로 반복하면 안전함
name, size(10진 문자열), sha256과 선택 사항인 labels, metadata로 설명하는 파일 하나의 업로드를 예약하고, 201과 함께 세션(pending, 7일간 유효)과 그 Location을 반환합니다. Idempotency-Key 헤더(문자, 숫자, _.:- 1–128자)는 필수이며, 같은 키와 같은 설명이면 같은 세션을 반환하고 설명이 다르면 409 idempotency_mismatch입니다. 크기는 리포지토리 할당량과 서버 용량에 대해 즉시 예약되며, 초과하면 507입니다. 이후 바이트 전체를 putUploadContent로 보내거나, putUploadPart로 파트별로 보낸 뒤 completeUpload로 마칩니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
Idempotency-Key | 헤더 | string | 예 | 128자 이하 |
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
name | string | 예 | 1–240자 |
size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
metadata | string 맵 | 아니요 | 항목 32개 이하 |
응답 201
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
repository | string | 예 | — |
status | string | 예 | pending, available, cancelled 중 하나 |
createdAt | string (date-time) | 예 | — |
expiresAt | string (date-time) | 예 | — |
descriptor | object | 예 | — |
descriptor.name | string | 예 | 1–240자 |
descriptor.size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
descriptor.sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
descriptor.labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
descriptor.metadata | string 맵 | 아니요 | 항목 32개 이하 |
응답: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","size":"1024","sha256":"<sha256: SHA-256>"}'업로드 조회
GET HEAD /api/v1/repositories/{repository}/uploads/{id}
액세스: 리포지토리 권한: upload.read; 파일 키: write · 재시도: 반복해도 안전함(읽기)
세션과 그 status(pending, 게시되면 available, cancelled), 만료 시각, 선언된 디스크립터를 반환합니다. putUploadContent 또는 completeUpload의 응답을 받지 못했다면 가장 먼저 이 작업을 호출합니다. available이면 아티팩트가 같은 ID로 게시된 것입니다. 업로드를 만든 사용자만 볼 수 있으며 그 외에는 404입니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
repository | string | 예 | — |
status | string | 예 | pending, available, cancelled 중 하나 |
createdAt | string (date-time) | 예 | — |
expiresAt | string (date-time) | 예 | — |
descriptor | object | 예 | — |
descriptor.name | string | 예 | 1–240자 |
descriptor.size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
descriptor.sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
descriptor.labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
descriptor.metadata | string 맵 | 아니요 | 항목 32개 이하 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"업로드 취소
DELETE /api/v1/repositories/{repository}/uploads/{id}
액세스: 리포지토리 권한: upload.cancel; 파일 키: write · 재시도: 업로드를 다시 읽은 후 결정
보류 중인 업로드를 취소하고 상태 cancelled로 반환합니다. 게시된 업로드는 취소할 수 없습니다(409 upload_state). 받은 바이트는 즉시 숨겨지지만, 리포지토리의 온라인 물리적 정리(setCleanup, 기본값은 꺼짐)가 유예 기간이 지난 뒤 제거할 때까지 할당량에 계속 예약되어 있습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
repository | string | 예 | — |
status | string | 예 | pending, available, cancelled 중 하나 |
createdAt | string (date-time) | 예 | — |
expiresAt | string (date-time) | 예 | — |
descriptor | object | 예 | — |
descriptor.name | string | 예 | 1–240자 |
descriptor.size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
descriptor.sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
descriptor.labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
descriptor.metadata | string 맵 | 아니요 | 항목 32개 이하 |
응답: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"파일 전체를 한 번의 요청으로 업로드
PUT /api/v1/repositories/{repository}/uploads/{id}/content
액세스: 리포지토리 권한: upload.write, upload.complete; 파일 키: write · 재시도: 업로드를 다시 읽은 후 결정
요청 본문을 보류 중인 업로드의 전체 콘텐츠로 스트리밍하고, 선언된 크기와 SHA-256에 맞는지 검사하여(불일치는 422) 아티팩트를 게시합니다. 응답은 상태가 available인 업로드입니다. 중단된 요청은 재개할 것이 없으므로, getUpload로 업로드를 확인한 뒤 파일을 0바이트부터 다시 보냅니다. 이미 파트가 있는 업로드에는 사용할 수 없으며(409 upload_state), 한 요청은 서버의 업로드 제한 시간(기본 30분) 안에 끝나야 하므로 큰 파일은 파트로 나누어 보냅니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
요청 본문 (application/octet-stream)
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
repository | string | 예 | — |
status | string | 예 | pending, available, cancelled 중 하나 |
createdAt | string (date-time) | 예 | — |
expiresAt | string (date-time) | 예 | — |
descriptor | object | 예 | — |
descriptor.name | string | 예 | 1–240자 |
descriptor.size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
descriptor.sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
descriptor.labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
descriptor.metadata | string 맵 | 아니요 | 항목 32개 이하 |
응답: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @file업로드 완료
POST /api/v1/repositories/{repository}/uploads/{id}/complete
액세스: 리포지토리 권한: upload.complete; 파일 키: write · 재시도: 업로드를 다시 읽은 후 결정
저장된 파트를 순서대로 조립하고 파일 전체를 선언된 크기와 SHA-256에 대해 검사한 뒤 아티팩트를 게시하며, 상태가 available인 업로드를 반환합니다. 이미 게시된 업로드에 다시 호출하면 같은 결과를 반환하므로, 응답이 유실된 완료도 이 호출로 복구할 수 있습니다. 파트가 빠져 있으면 409 parts_incomplete, 내용이 맞지 않으면 422입니다. 요청이 시간 초과될 수 있는 매우 큰 파일에는 대신 enqueueCompletion을 사용합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
repository | string | 예 | — |
status | string | 예 | pending, available, cancelled 중 하나 |
createdAt | string (date-time) | 예 | — |
expiresAt | string (date-time) | 예 | — |
descriptor | object | 예 | — |
descriptor.name | string | 예 | 1–240자 |
descriptor.size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
descriptor.sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
descriptor.labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
descriptor.metadata | string 맵 | 아니요 | 항목 32개 이하 |
응답: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
-H "Authorization: Bearer $ARKVORY_TOKEN"