パス指定ファイル
リポジトリ内のパスで指定するファイル：リビジョン、履歴、復元、1回のリクエストで扱うrawファイル。
このグループの操作と、それぞれのアクセスルール、再試行ルール、パラメーター、レスポンスです。すべてのリクエストにはキーを付けます：Authorization: Bearer <key>（「認証」を参照）。
操作
プレフィックスによるファイルパスの一覧表示
GET HEAD /api/v1/repositories/{repository}/assets
アクセス: リポジトリ権限：asset.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
prefix（リテラルでありパターンではない。空にするとすべて）で始まるすべてのファイルパスを、パス順に返します。各項目には現在のリビジョンとアーティファクトIDが含まれます。ページングはありません。一致が1000件を超えると、より狭いプレフィックスを求める400になるため、大きなツリーにはlistAssetPageを使用してください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
prefix | クエリ | string | いいえ | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | いいえ | — |
items[].path | string | はい | — |
items[].revision | integer | はい | 1～2147483647 |
items[].artifactId | string (uuid) | はい | — |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ファイルパスのページごとの一覧表示
GET HEAD /api/v1/repositories/{repository}/assets/page
アクセス: リポジトリ権限：asset.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
prefix（リテラル。空にするとすべて）で始まる現在のファイルパスを、UTF-8のバイト順で返します。各項目には現在のリビジョンとアーティファクトIDが含まれます。ページにはlimit件（1〜100、既定は50）が含まれ、続きは不透明なnextをafterに設定して取得します。ページはスナップショットではありません。リクエストの間に変更されたパスは、新しいリビジョンで現れるか、次に走査し直すまで見落とされることがあります。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
prefix | クエリ | string | いいえ | 1024文字以内; 既定値：``; Case-sensitive literal prefix; % and _ are ordinary characters. |
after | クエリ | string | いいえ | ^[A-Za-z0-9_-]+$に一致; 1～8192文字 |
limit | クエリ | integer | いいえ | 1～100; 既定値：50 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 100個以内の要素 |
items[].path | string | はい | — |
items[].revision | integer | はい | 1～2147483647 |
items[].artifactId | string (uuid) | はい | — |
next | string | はい | ^[A-Za-z0-9_-]+$に一致; 1～8192文字; nullも可; リポジトリとプレフィックスに結び付けられた不透明なカーソル。末尾ではnull。アクセスを与えることはありません。 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets/page" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ファイルパスの現在のリビジョンの取得
GET HEAD /api/v1/repositories/{repository}/asset
アクセス: リポジトリ権限：asset.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
pathの現在のrevisionと、それが指すアーティファクトのIDを返します。未知のパスは404です。パスは/区切りのセグメントからなる1〜1024文字で、空のセグメント、.や..のセグメント、\、:、制御文字を含めることはできません。バイト列はdownloadAssetContentでダウンロードするか、リビジョンをsetAssetのexpectedRevisionとして渡してください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
path | クエリ | string | はい | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
path | string | はい | — |
revision | integer | はい | 1～2147483647 |
artifactId | string (uuid) | はい | — |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ファイルパスのアーティファクトへの割り当て
PUT /api/v1/repositories/{repository}/asset
アクセス: リポジトリ権限：asset.write, artifact.read; ファイルキー：read, write · 再試行: 想定するリビジョンを指定した場合のみ再試行（compare-and-swap）
pathが、同じリポジトリの公開済みアーティファクトを新しいリビジョンとして指すようにします。expectedRevisionは、パスを作成するときは0、置き換えるときは現在のリビジョンとし、そうでない場合は409 revision_mismatchになります。以前のリビジョンは履歴に残り、それらのアーティファクトが削除されないよう保護します。バイト列の保存と命名を1回のリクエストで行うには、putRawFileを使用してください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
path | string | はい | — |
artifactId | string (uuid) | はい | — |
expectedRevision | integer | はい | 0～2147483646 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
path | string | はい | — |
revision | integer | はい | 1～2147483647 |
artifactId | string (uuid) | はい | — |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"<path>","artifactId":"00000000-0000-4000-8000-000000000000","expectedRevision":0}'ファイルパスのリビジョンの一覧表示
GET HEAD /api/v1/repositories/{repository}/asset/history
アクセス: リポジトリ権限：asset.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
pathのリビジョンを新しい順に、1ページ50件で返します。各項目には、アーティファクト、実行者、時刻、そして復元の場合はコピー元のsourceRevisionが含まれます（初期のサーバーバージョンで記録されたリビジョンでは、実行者と時刻はnullです）。続きはbeforeにnextを設定して取得します。未知のパスは404です。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
path | クエリ | string | はい | — |
before | クエリ | integer | いいえ | 1～2147483647; Only revisions strictly smaller than this value |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 50個以内の要素 |
items[].path | string | はい | — |
items[].revision | integer | はい | 1～2147483647 |
items[].artifactId | string (uuid) | はい | — |
items[].actor | string | はい | nullも可; マイグレーション4より前に記録された履歴ではnull |
items[].createdAt | string (date-time) | はい | nullも可; マイグレーション4より前に記録された履歴ではnull |
items[].sourceRevision | integer | はい | 1～2147483647; nullも可; 復元されたリビジョン。通常の置換ではnull |
next | integer | はい | 1～2147483647; nullも可; この値より前のエントリを返すカーソル（この値自体は含まない）。末尾ではnull |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ファイルパスの特定のリビジョンの取得
GET HEAD /api/v1/repositories/{repository}/asset/revision
アクセス: リポジトリ権限：asset.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
pathのリビジョンrevisionを、アーティファクトID、実行者、時刻、復元元とともに返します。リビジョンは決して変わらないため、アーティファクトIDはキャッシュできます。ダウンロードにはdownloadArtifactを使用してください。パスまたはリビジョンが存在しない場合は404です。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
path | クエリ | string | はい | — |
revision | クエリ | integer | はい | 1～2147483647 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
path | string | はい | — |
revision | integer | はい | 1～2147483647 |
artifactId | string (uuid) | はい | — |
actor | string | はい | nullも可; マイグレーション4より前に記録された履歴ではnull |
createdAt | string (date-time) | はい | nullも可; マイグレーション4より前に記録された履歴ではnull |
sourceRevision | integer | はい | 1～2147483647; nullも可; 復元されたリビジョン。通常の置換ではnull |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ファイルパスの以前のリビジョンの復元
POST /api/v1/repositories/{repository}/asset/restore
アクセス: リポジトリ権限：asset.restore, asset.read, artifact.read; ファイルキー：read, write · 再試行: 想定するリビジョンを指定した場合のみ再試行（compare-and-swap）
sourceRevisionのアーティファクトを指すpathの新しいリビジョンを追加します。何もコピーされず、リビジョンも削除されません。expectedRevisionは現在のリビジョン（1以上）でなければならず、そうでない場合は409 revision_mismatchになります。そのため、すでに成功した復元を繰り返すと、2回目の復元ではなく409になります。新しいリビジョンにはsourceRevisionが記録され、変更は同じトランザクション内で監査されます。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
path | string | はい | — |
sourceRevision | integer | はい | 1～2147483647 |
expectedRevision | integer | はい | 1～2147483646 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
path | string | はい | — |
revision | integer | はい | 1～2147483647 |
artifactId | string (uuid) | はい | — |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/restore" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"<path>","sourceRevision":1,"expectedRevision":1}'パスによるファイルのダウンロード
GET HEAD /api/v1/repositories/{repository}/asset/content
アクセス: リポジトリ権限：content.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
pathを現在のリビジョンに解決し、そのアーティファクトをdownloadArtifactと同様に、Range、If-Range、If-None-Match、HEADに対応してストリームで返します。パスはリクエストのたびに解決されるため、再開するときは返されたETagをIf-Rangeに設定してください。パスがその後更新されていた場合、応答は新旧が混在したものではなく、新しいファイル全体になります。URLにパスを含める同等の操作がdownloadRawFileです。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
Range | ヘッダー | string | いいえ | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | ヘッダー | string | いいえ | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | ヘッダー | string | いいえ | Matching ETag returns 304, including HEAD. |
Arkvory-Download-Id | ヘッダー | string | いいえ | ^[A-Za-z0-9_-]{16,64}$に一致; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time. |
Arkvory-Queue-Ticket | ヘッダー | string | いいえ | 80文字以内; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored. |
Arkvory-Download-Class | ヘッダー | string | いいえ | 次のいずれか：interactive, release, bulk, background; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied. |
path | クエリ | string | はい | — |
レスポンス: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file1回のリクエストでパスにファイルをアップロード
PUT /api/v1/repositories/{repository}/raw/{assetPath}
アクセス: リポジトリ権限：upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; ファイルキー：write · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
スクリプトやCI（curl -T）向けに、任意のメディアタイプのリクエストボディを、URL内のパスの新しいリビジョンとして保存します。応答は201で、パス、リビジョン、アーティファクトを返します。X-Checksum-Sha256とContent-Lengthを付けると、バイト列はストレージへ直接ストリームされて検証されます。付けない場合は、先に一時領域へ保存されてハッシュが計算されます（指定したチェックサムとボディが一致しなければ422）。現在のリビジョンと同じバイト列は何も追加せず、created: falseを伴う200で応答します。If-None-Match: *は作成のみを行い（409 already_exists）、同じパスに同時に書き込んだ側は409 revision_mismatchになります。非常に大きなファイルには、再開可能なアップロードセッションを使用してください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
assetPath | パス | string | はい | 1～1024文字; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
X-Checksum-Sha256 | ヘッダー | string | いいえ | ^[a-fA-F0-9]{64}$に一致; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422). |
If-None-Match | ヘッダー | string | いいえ | 次のいずれか：*; "*": store only when the path does not exist yet (409 already_exists). |
リクエスト本文 (application/octet-stream)
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
path | string | はい | — |
revision | integer | はい | 1以上 |
created | boolean | はい | — |
artifact | object | はい | — |
artifact.id | string (uuid) | はい | — |
artifact.size | string | はい | 10進数字で表した整数（文字列として送信） |
artifact.sha256 | string | はい | SHA-256：小文字の16進数字64桁 |
レスポンス: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
例
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileURLパスによるファイルのダウンロード
GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}
アクセス: リポジトリ権限：content.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
URL内のパスの現在のリビジョンを、downloadArtifactと同様に、Range、If-Range、If-None-Match、HEADに対応してストリームで返します。アーティファクトはX-Arkvory-Artifact-Idで分かります。パスはリクエストのたびに解決されるため、再開するときは返されたETagをIf-Rangeに設定するか、アーティファクトをIDでダウンロードしてください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
assetPath | パス | string | はい | 1～1024文字; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
Range | ヘッダー | string | いいえ | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | ヘッダー | string | いいえ | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | ヘッダー | string | いいえ | Matching ETag returns 304, including HEAD. |
Arkvory-Download-Id | ヘッダー | string | いいえ | ^[A-Za-z0-9_-]{16,64}$に一致; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time. |
Arkvory-Queue-Ticket | ヘッダー | string | いいえ | 80文字以内; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored. |
Arkvory-Download-Class | ヘッダー | string | いいえ | 次のいずれか：interactive, release, bulk, background; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied. |
レスポンス: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file