アップロード
再開可能なアップロード：アップロードセッションを作成し、バイトを一括またはパートに分けて送信し、完了させて、その完了ジョブを追跡します。
このグループの操作と、それぞれのアクセスルール、再試行ルール、パラメーター、レスポンスです。すべてのリクエストにはキーを付けます：Authorization: Bearer <key>（「認証」を参照）。
操作
受信済みパートの一覧表示
GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts
アクセス: リポジトリ権限：upload.read; ファイルキー：write · 再試行: 再試行しても安全（読み取り）
partBytes（アップロードの作成時に確定したこのアップロードのパートサイズ。8MiBで、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になります。パートは任意の順序で到着してかまいませんが、1つのアップロードが同時に処理できるリクエストは1つです（同時に送ると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（アップロードが公開済み）、failed（errorCodeを伴う）のいずれかで、試行回数も含まれます。ワーカーは間隔を延ばしながら最大5回試行しますが、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で記述される1つのファイルのために、アップロードを予約します。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"ファイル全体を1回のリクエストでアップロード
PUT /api/v1/repositories/{repository}/uploads/{id}/content
アクセス: リポジトリ権限：upload.write, upload.complete; ファイルキー：write · 再試行: アップロードを再取得してから判断
リクエストボディをストリームとして、保留中のアップロードの完全な内容として受け取り、宣言されたサイズおよびSHA-256と照合して（不一致の場合は422）アーティファクトを公開します。応答は、ステータスavailableのアップロードです。リクエストが中断した場合、再開できるものは残りません。getUploadでアップロードを読み取ってから、ファイルを先頭のバイトから送り直してください。すでにパートがあるアップロードには使用できません（409 upload_state）。また、1回のリクエストはサーバーのアップロード期限（既定は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"