アーティファクトとカタログ
公開済みのアーティファクト：一覧、詳細、コンテンツ、注釈、参照、検索、カタログの監査とその変更フィード。
このグループの操作と、それぞれのアクセスルール、再試行ルール、パラメーター、レスポンスです。すべてのリクエストにはキーを付けます：Authorization: Bearer <key>（「認証」を参照）。
操作
アーティファクトのアノテーションの取得
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations
アクセス: リポジトリ権限：annotation.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
公開済みアーティファクトの現在のラベル、メタデータ、コレクションを、そのrevisionとともに返します。リビジョン0は、一度も置換されていないことを意味します。ラベルとメタデータはアップロードの作成時に指定されたもので、コレクションは空です。このリビジョンをsetAnnotationsのexpectedRevisionとして渡してください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
revision | integer | はい | 0～2147483647 |
labels | stringの配列 | はい | 32個以内の要素 |
metadata | stringのマップ | はい | 32個以内のエントリ |
collections | stringの配列 | はい | 32個以内の要素 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトのアノテーションの置換
PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations
アクセス: リポジトリ権限：annotation.write, artifact.read; ファイルキー：read, write · 再試行: 想定するリビジョンを指定した場合のみ再試行（compare-and-swap）
公開済みアーティファクトのlabels、metadata、collectionsを一括で置換します。valueに含めなかったフィールドは空になります。expectedRevisionは現在のリビジョン（最初の変更では0）でなければならず、そうでない場合は409 revision_mismatchになります。その場合はアノテーションを読み取り直して、変更をもう一度適用してください。ラベルとコレクションはそれぞれ最大32個（英字、数字、_.:-からなる1〜64文字）、メタデータは最大32エントリ（値は1024文字まで）です。バイト列と元のディスクリプターは変わりません。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
expectedRevision | integer | はい | 0～2147483646 |
value | object | はい | — |
value.labels | stringの配列 | いいえ | 32個以内の要素 |
value.metadata | stringのマップ | いいえ | 32個以内のエントリ |
value.collections | stringの配列 | いいえ | 32個以内の要素 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
revision | integer | はい | 0～2147483647 |
labels | stringの配列 | はい | 32個以内の要素 |
metadata | stringのマップ | はい | 32個以内のエントリ |
collections | stringの配列 | はい | 32個以内の要素 |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"value":{}}'アーティファクトのUPackパッケージとしての登録
POST /api/v1/repositories/{repository}/artifacts/{id}/package
アクセス: リポジトリ権限：package.publish, artifact.read; ファイルキー：read, write · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
公開済みアーティファクトをUPack ZIPとして開き、ルートのupack.json（name、任意のgroup、SemVerのversion）を読み取って、そのパッケージバージョンを登録します。安全でないアーカイブや不正なアーカイブは400で拒否されます。バージョンは不変です。同じアーティファクトを再度登録すると同じエントリが返り、既存のグループ、名前、バージョンの組（大文字小文字を区別せずに比較）に別のアーティファクトを登録しようとすると409 version_existsになります。登録後、そのバージョンはlistPackagesに表示され、名前、範囲、ステージで解決できるようになります。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
group | string | いいえ | — |
name | string | いいえ | — |
version | string | いいえ | — |
artifactId | string (uuid) | いいえ | — |
manifest | object | いいえ | — |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトの検索
GET HEAD /api/v1/repositories/{repository}/search
アクセス: リポジトリ権限：artifact.list; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
公開済みアーティファクトを、q（名前または現在のメタデータ値に含まれる、大文字小文字を区別しない部分文字列）、現在のラベルとの完全一致label、collection、および必ず組で指定するmetadataKeyとmetadataValueの完全一致で検索します。指定したフィルターはすべて一致する必要があります。結果はID順に100件ずつのページで返り、各項目にはサイズ、作成時刻と公開時刻、現在のラベル、プロモーションステージが含まれます。続きはafterにnextを設定して取得します。メタデータとコレクションは返されないため、getAnnotationsで読み取ってください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
q | クエリ | string | いいえ | — |
label | クエリ | string | いいえ | — |
collection | クエリ | string | いいえ | — |
after | クエリ | string | いいえ | — |
metadataKey | クエリ | string | いいえ | ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$に一致; 64文字以内; Exact metadata key; requires metadataValue. |
metadataValue | クエリ | string | いいえ | 1024文字以内; Exact case-sensitive value; requires metadataKey. Empty string is allowed. |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 100個以内の要素 |
items[].id | string (uuid) | はい | — |
items[].name | string | はい | — |
items[].size | string | はい | 10進数字で表した整数（文字列として送信）; バイトサイズ（10進数の文字列） |
items[].createdAt | string (date-time) | はい | アップロードの予約時刻 |
items[].publishedAt | string (date-time) | はい | nullも可; 公開時刻。記録がない場合にのみnull |
items[].labels | stringの配列 | はい | 32個以内の要素; 現在のラベル。置換されている場合はアノテーション、そうでなければアップロード時のディスクリプター |
items[].stages | stringの配列 | はい | 16個以内の要素; 各要素：^[a-z0-9][a-z0-9_.-]{0,31}$に一致; 現在のプロモーションステージ（バイト順） |
next | string (uuid) | はい | nullも可; 満杯のページの最後のID。afterとして渡します |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
-H "Authorization: Bearer $ARKVORY_TOKEN"リポジトリのカタログ監査の取得
GET HEAD /api/v1/repositories/{repository}/audit
アクセス: リポジトリ権限：audit.read; ファイルキー：write · 再試行: 再試行しても安全（読み取り）
シーケンス番号after（既定は0）より後のリポジトリのカタログ変更を、古いものから最大100件返します。対象は、公開、削除、アノテーションと添付ファイルの変更、パッケージの登録、ファイルパスの変更、参照、ステージ、プロモーションで、それぞれに実行者、アクション、アーティファクト、時刻が含まれます。続きを読むには、ページの最後のsequenceをafterとして渡します。nextフィールドはありません。ダウンロードとサインインは含まれません。ミラーは、実行者を含まないlistCatalogChangesで変更に追従します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
after | クエリ | string | いいえ | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | いいえ | — |
items[].sequence | string | いいえ | — |
items[].actor | string | いいえ | — |
items[].action | string | いいえ | — |
items[].artifactId | string | いいえ | — |
items[].occurredAt | string (date-time) | いいえ | — |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトへの参照の追加
POST /api/v1/repositories/{repository}/artifacts/{id}/references
アクセス: リポジトリ権限：reference.write, artifact.read; ファイルキー：read, write · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
Arkvoryの外部の何かがこのアーティファクトを使用していることを、任意のkey（英字、数字、_.:/-からなる1〜256文字。たとえばデプロイ名）で記録します。参照があるアーティファクトは、すべての参照がなくなるまで、削除も保持ルールによる削除もできません。参照は呼び出し元に属し、同じキーを再度追加しても何も変わりません。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
key | string | はい | 256文字以内 |
レスポンス: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'アーティファクトからの参照の削除
DELETE /api/v1/repositories/{repository}/artifacts/{id}/references
アクセス: リポジトリ権限：reference.write, artifact.read; ファイルキー：read, write · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
アーティファクトから呼び出し元自身の参照keyを削除します。他の呼び出し元の参照は残ります。存在しないキーを削除した場合も成功します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
key | string | はい | 256文字以内 |
レスポンス: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'アーティファクトの一覧表示
GET HEAD /api/v1/repositories/{repository}/artifacts
アクセス: リポジトリ権限：artifact.list; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
リポジトリの公開済みアーティファクトをID順に、1ページあたりlimit件（1〜100、既定は50）で列挙します。続きはafterにnextを設定して取得します。ページが満杯のときは常にnextが設定されるため、最後のページが空になることがあります。各項目にはアップロード時に指定されたディスクリプターが含まれます。現在のラベルとメタデータはgetAnnotationsで取得できます。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
after | クエリ | string (uuid) | いいえ | — |
limit | クエリ | integer | いいえ | 1～100; 既定値：50 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | いいえ | — |
items[].id | string (uuid) | はい | — |
items[].repository | string | はい | — |
items[].status | string | はい | 次のいずれか：pending, available, cancelled |
items[].createdAt | string (date-time) | はい | — |
items[].expiresAt | string (date-time) | はい | — |
items[].descriptor | object | はい | — |
items[].descriptor.name | string | はい | 1～240文字 |
items[].descriptor.size | string | はい | 10進数字で表した整数（文字列として送信） |
items[].descriptor.sha256 | string | はい | SHA-256：小文字の16進数字64桁 |
items[].descriptor.labels | stringの配列 | いいえ | 32個以内の要素; 各要素：64文字以内 |
items[].descriptor.metadata | stringのマップ | いいえ | 32個以内のエントリ |
next | string | いいえ | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトの取得
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}
アクセス: リポジトリ権限：artifact.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
公開済みアーティファクトを返します。ID、リポジトリ、ステータス、作成時刻、アップロード時に指定されたディスクリプター（名前、サイズ、SHA-256、元のラベルとメタデータ）が含まれます。保留中、キャンセル済み、削除済みのアーティファクトは404で応答します。バイト列を読み取るにはdownloadArtifactを使用してください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
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/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトの削除
DELETE /api/v1/repositories/{repository}/artifacts/{id}
アクセス: リポジトリ権限：artifact.delete · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
公開済みアーティファクトを論理削除します。一覧、検索、ダウンロードからはただちに消え、そのバイト列はリポジトリの物理クリーンアップ（setCleanup、既定ではオフ）によって猶予期間の経過後に回収されます。expectedAnnotationRevisionは現在のアノテーションのリビジョンと等しくなければなりません。応答は200で、outcomeはdeleted、already_deleted、changed（リビジョンが異なる）、not_found、または削除を妨げているもの（参照、ファイルパスのリビジョン、ビルドの添付ファイル、プロモーションステージ）を示すblockersを伴うprotectedのいずれかです。事前にinspectArtifactDeletionで確認してください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
expectedAnnotationRevision | integer | はい | 0～2147483647 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
id | string (uuid) | はい | — |
outcome | string | はい | 次のいずれか：deleted, already_deleted, protected, changed, not_eligible, not_found |
blockers | stringの配列 | はい | 4個以内の要素; 要素の重複なし; 各要素：次のいずれか：reference, asset_history, attachment_history, protected_label, promotion_stage |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedAnnotationRevision":0}'アーティファクトのダウンロード
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content
アクセス: リポジトリ権限：content.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
元のバイト列を、Content-Length、Content-Disposition（アーティファクト名）、強いETag（"sha256:<hex>"）とともにストリームで返します。単一のRangeには206で応答し（満たせない場合は416）、ETagを指定したIf-Rangeで安全に再開でき、If-None-Matchには304で応答します。HEADは本文なしで同じヘッダーを返し、Rangeは無視します。Authorizationヘッダーの代わりに、createDownloadLinkで作成したダウンロードリンクをtokenとして付けることもできます。ダウンロードは、サーバーのダウンロード受け入れ枠に空きが出るまで待機します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
Range | ヘッダー | string | いいえ | — |
If-Range | ヘッダー | string | いいえ | — |
If-None-Match | ヘッダー | string | いいえ | — |
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. |
token | クエリ | string | いいえ | ^dtl_[A-Za-z0-9_-]{43}$に一致; Download link from POST …/artifacts/{id}/links, instead of an Authorization header |
レスポンス: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileサイトの概要を読む
GET HEAD /api/v1/fleet/overview
アクセス: 管理者 · 再試行: 再試行しても安全（読み取り）
管理対象サイトとこのインストールのアラート（重大なものから critical、warning、info）と、それらの間のミラーのリンク。直近のバックグラウンド読み取りから最大 5 秒に 1 回作成されます。どの管理対象サイトもそのアドレスで応答しないソースは external:<origin>、このインストールは self で、ARKVORY_SITE_URL を設定したときだけこのインストールへのリンクが現れます。書き込みプロセスのみが応答します。
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
generatedAt | string (date-time) | はい | — |
self | object | はい | — |
self.name | string | はい | — |
self.version | string | はい | — |
self.url | string | はい | nullも可 |
alerts | objectの配列 | はい | — |
alerts[].site | string | はい | — |
alerts[].name | string | はい | — |
alerts[].kind | string | はい | 次のいずれか：unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew |
alerts[].severity | string | はい | 次のいずれか：critical, warning, info |
alerts[].subject | string | はい | nullも可 |
alerts[].since | string (date-time) | はい | nullも可 |
links | objectの配列 | はい | — |
links[].from | string | はい | — |
links[].to | string | はい | — |
links[].repository | string | はい | — |
links[].sourceRepository | string | はい | — |
links[].mode | string | はい | 次のいずれか：mirror, import |
links[].lagChanges | string | はい | 10進数字で表した整数（文字列として送信）; nullも可 |
links[].failing | boolean | はい | — |
links[].stale | boolean | いいえ | — |
external | stringの配列 | はい | — |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"管理しているサイトの一覧
GET HEAD /api/v1/fleet/sites
アクセス: 管理者 · 再試行: 再試行しても安全（読み取り）
このインストールが管理するサイト（ADR 0077）と、各サイトが最後に報告した内容：state（ok、または読めなかった理由：unreachable、certificate、revoked、invalid、refused）、最後に確認できた時刻、最後の topology。サイトはバックグラウンドで30秒ごとに読み取ります。サイトのキーは返しません。
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 256個以内の要素 |
items[].id | string (uuid) | はい | — |
items[].name | string | はい | — |
items[].url | string | はい | — |
items[].fingerprint | string | はい | ^[0-9a-f]{64}$に一致; nullも可 |
items[].addedBy | string | はい | — |
items[].addedAt | string (date-time) | はい | — |
items[].seenAt | string (date-time) | はい | nullも可 |
items[].state | string | はい | 次のいずれか：pending, ok, unreachable, certificate, revoked, invalid, refused |
items[].error | string | はい | nullも可 |
items[].topology | object | はい | nullも可 |
items[].topology.collectedAt | string (date-time) | はい | — |
items[].topology.site | object | はい | — |
items[].topology.health | object | はい | — |
items[].topology.replication | object | はい | nullも可 |
items[].topology.gateways | objectの配列 | はい | 16個以内の要素 |
items[].topology.mirrors | objectの配列 | はい | 64個以内の要素 |
items[].topology.updates | object | はい | nullも可 |
items[].topology.downloads | object | はい | — |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN"サイトとペアリング
POST /api/v1/fleet/sites
アクセス: 管理者 · 再試行: 自動的に再試行しない
サイトとペアリングします：コントローラーが再接続し、証明書は管理者が確認した fingerprint のままでなければなりません（loopback の HTTP は null）。サイトで作成したペアリング code をキーと交換し、キーは ARKVORY_FLEET_KEY_FILE で封印します。応答の前にサイトを一度読み取ります。キーファイルがなければ応答は 503 です。
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
url | string | はい | — |
fingerprint | string | はい | ^[0-9a-f]{64}$に一致; nullも可 |
code | string | はい | 32文字以内 |
レスポンス 201
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
id | string (uuid) | はい | — |
name | string | はい | — |
url | string | はい | — |
fingerprint | string | はい | ^[0-9a-f]{64}$に一致; nullも可 |
addedBy | string | はい | — |
addedAt | string (date-time) | はい | — |
seenAt | string (date-time) | はい | nullも可 |
state | string | はい | 次のいずれか：pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | はい | nullも可 |
topology | object | はい | nullも可 |
topology.collectedAt | string (date-time) | はい | — |
topology.site | object | はい | — |
topology.site.name | string | はい | — |
topology.site.version | string | はい | — |
topology.site.schema | integer | はい | 0以上 |
topology.site.role | string | はい | 次のいずれか：api, reader |
topology.health | object | はい | — |
topology.health.available | boolean | はい | — |
topology.health.writable | boolean | はい | — |
topology.health.draining | boolean | はい | — |
topology.replication | object | はい | nullも可 |
topology.replication.copies | integer | はい | 0～16 |
topology.replication.required | integer | はい | 1～16 |
topology.replication.singleCopyUntil | string (date-time) | はい | nullも可 |
topology.replication.node | string | いいえ | 63文字以内 |
topology.replication.profile | string | いいえ | 次のいずれか：ha-2, ha-3 |
topology.replication.peers | objectの配列 | いいえ | 16個以内の要素 |
topology.gateways | objectの配列 | はい | 16個以内の要素 |
topology.gateways[].slot | integer | はい | 0以上 |
topology.gateways[].active | boolean | はい | — |
topology.gateways[].expiresAt | string (date-time) | はい | — |
topology.mirrors | objectの配列 | はい | 64個以内の要素 |
topology.mirrors[].repository | string | はい | — |
topology.mirrors[].mode | string | はい | 次のいずれか：mirror, import |
topology.mirrors[].upstream | string | はい | — |
topology.mirrors[].sourceRepository | string | はい | — |
topology.mirrors[].phase | string | はい | — |
topology.mirrors[].errorCode | string | はい | nullも可 |
topology.mirrors[].checkedAt | string (date-time) | はい | nullも可 |
topology.mirrors[].syncedAt | string (date-time) | はい | nullも可 |
topology.mirrors[].lagChanges | string | はい | 10進数字で表した整数（文字列として送信）; nullも可 |
topology.mirrors[].copiedArtifacts | integer | はい | 0以上 |
topology.mirrors[].copiedBytes | string | はい | 10進数字で表した整数（文字列として送信） |
topology.updates | object | はい | nullも可 |
topology.updates.currentVersion | string | はい | — |
topology.updates.latest | string | はい | nullも可 |
topology.updates.phase | string | はい | — |
topology.updates.error | string | はい | nullも可 |
topology.updates.automatic | boolean | はい | — |
topology.updates.heartbeatAt | string (date-time) | はい | — |
topology.downloads | object | はい | — |
topology.downloads.strategy | string | はい | 次のいずれか：ordered, smallest-first, shared |
topology.downloads.sessions | integer | はい | 0以上 |
topology.downloads.active | integer | はい | 0以上 |
topology.downloads.waiting | integer | はい | 0以上 |
topology.downloads.oldestWaitSeconds | integer | はい | 0以上 |
topology.downloads.bytesPerSecond | integer | はい | 0以上 |
レスポンス: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>","fingerprint":"<fingerprint>","code":"<code>"}'サイトの証明書を読む
POST /api/v1/fleet/sites/probe
アクセス: 管理者 · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
アドレスに接続し、何も送らずにサイトの証明書を読みます：ペアリング前に fingerprint をサイトの管理者が見ているものと比べてください。
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
url | string | はい | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
url | string | はい | — |
certificate | object | はい | nullも可 |
certificate.fingerprint | string | はい | ^[0-9a-f]{64}$に一致 |
certificate.subject | string | はい | — |
certificate.issuer | string | はい | — |
certificate.validTo | string (date-time) | はい | — |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'サイトを忘れる
DELETE /api/v1/fleet/sites/{id}
アクセス: 管理者 · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
ここでサイトと封印されたキーを削除します。サイト側でもこのコントローラーを取り消してください。それまでキーはそこで有効です。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
id | パス | string (uuid) | はい | — |
レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
例
curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"サイトのカタログを読む
GET HEAD /api/v1/fleet/sites/{id}/read
アクセス: 管理者 · 再試行: 再試行しても安全（読み取り）
カタログの読み取りを 1 回、管理対象サイトに渡し、その応答をそのまま返します：リポジトリ、検索、アーティファクト、注釈、ステージ、パッケージ、ファイルのページと履歴、ストレージ使用量、ミラーの状態。path はクエリ付きのサイトのルートです。その他のルートとファイルのバイトは 400 で拒否されます。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
id | パス | string (uuid) | はい | — |
path | クエリ | string | はい | ^/api/v1/に一致; 2048文字以内; A read route of the site with its query, from a fixed list: catalog metadata (repositories, search, artifacts, annotations, stages, packages, file pages and history, storage usage, mirror state), download queue settings and update state. Never file bytes. |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"サイトの設定を変更する
POST /api/v1/fleet/sites/{id}/change
アクセス: 管理者 · 再試行: 自動的に再試行しない
変更を 1 つ管理対象サイトに渡し、その応答をそのまま返します。path は次のいずれかのルートです：/api/v1/system/downloads/settings（ダウンロードキューの設定、PUT で送信）または /api/v1/system/updates/requests（更新リクエスト、POST で送信）。本文はそのままサイトに届きます。サイトがリビジョンまたはリクエスト id を確認するため、繰り返された変更が二重に適用されることはありません。その他のパスは 400 で拒否されます。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
id | パス | string (uuid) | はい | — |
path | クエリ | string | はい | ^/api/v1/に一致; 2048文字以内; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests. |
リクエスト本文 (application/json)
レスポンス: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'今すぐサイトを読む
POST /api/v1/fleet/sites/{id}/refresh
アクセス: 管理者 · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
次の巡回を待たずに今サイトを読み、新しい状態で返します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
id | パス | string (uuid) | はい | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
id | string (uuid) | はい | — |
name | string | はい | — |
url | string | はい | — |
fingerprint | string | はい | ^[0-9a-f]{64}$に一致; nullも可 |
addedBy | string | はい | — |
addedAt | string (date-time) | はい | — |
seenAt | string (date-time) | はい | nullも可 |
state | string | はい | 次のいずれか：pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | はい | nullも可 |
topology | object | はい | nullも可 |
topology.collectedAt | string (date-time) | はい | — |
topology.site | object | はい | — |
topology.site.name | string | はい | — |
topology.site.version | string | はい | — |
topology.site.schema | integer | はい | 0以上 |
topology.site.role | string | はい | 次のいずれか：api, reader |
topology.health | object | はい | — |
topology.health.available | boolean | はい | — |
topology.health.writable | boolean | はい | — |
topology.health.draining | boolean | はい | — |
topology.replication | object | はい | nullも可 |
topology.replication.copies | integer | はい | 0～16 |
topology.replication.required | integer | はい | 1～16 |
topology.replication.singleCopyUntil | string (date-time) | はい | nullも可 |
topology.replication.node | string | いいえ | 63文字以内 |
topology.replication.profile | string | いいえ | 次のいずれか：ha-2, ha-3 |
topology.replication.peers | objectの配列 | いいえ | 16個以内の要素 |
topology.gateways | objectの配列 | はい | 16個以内の要素 |
topology.gateways[].slot | integer | はい | 0以上 |
topology.gateways[].active | boolean | はい | — |
topology.gateways[].expiresAt | string (date-time) | はい | — |
topology.mirrors | objectの配列 | はい | 64個以内の要素 |
topology.mirrors[].repository | string | はい | — |
topology.mirrors[].mode | string | はい | 次のいずれか：mirror, import |
topology.mirrors[].upstream | string | はい | — |
topology.mirrors[].sourceRepository | string | はい | — |
topology.mirrors[].phase | string | はい | — |
topology.mirrors[].errorCode | string | はい | nullも可 |
topology.mirrors[].checkedAt | string (date-time) | はい | nullも可 |
topology.mirrors[].syncedAt | string (date-time) | はい | nullも可 |
topology.mirrors[].lagChanges | string | はい | 10進数字で表した整数（文字列として送信）; nullも可 |
topology.mirrors[].copiedArtifacts | integer | はい | 0以上 |
topology.mirrors[].copiedBytes | string | はい | 10進数字で表した整数（文字列として送信） |
topology.updates | object | はい | nullも可 |
topology.updates.currentVersion | string | はい | — |
topology.updates.latest | string | はい | nullも可 |
topology.updates.phase | string | はい | — |
topology.updates.error | string | はい | nullも可 |
topology.updates.automatic | boolean | はい | — |
topology.updates.heartbeatAt | string (date-time) | はい | — |
topology.downloads | object | はい | — |
topology.downloads.strategy | string | はい | 次のいずれか：ordered, smallest-first, shared |
topology.downloads.sessions | integer | はい | 0以上 |
topology.downloads.active | integer | はい | 0以上 |
topology.downloads.waiting | integer | はい | 0以上 |
topology.downloads.oldestWaitSeconds | integer | はい | 0以上 |
topology.downloads.bytesPerSecond | integer | はい | 0以上 |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ペアリングコードを作成
POST /api/v1/system/fleet/pairings
アクセス: 管理者 · 再試行: 自動的に再試行しない
コントローラーの管理者がこのサイトを管理するために入力する、10分間有効な使い捨てコードを作成します。コードは一度だけ表示され、ハッシュとしてのみ保存されます。作成できるのはサイトのグローバル管理者だけです。
レスポンス 201
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
code | string | はい | ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$に一致 |
expiresAt | string (date-time) | はい | — |
fingerprint | string | はい | ^[0-9a-f]{64}$に一致; nullも可 |
レスポンス: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"このサイトのコントローラー一覧
GET HEAD /api/v1/system/fleet/controllers
アクセス: 管理者 · 再試行: 再試行しても安全（読み取り）
このサイトを管理できるコントローラーを一覧表示します：名前、誰がいつペアリングしたか、キーが最後に使われた時刻。
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 100個以内の要素 |
items[].id | string (uuid) | はい | — |
items[].name | string | はい | — |
items[].pairedBy | string | はい | — |
items[].pairedAt | string (date-time) | はい | — |
items[].usedAt | string (date-time) | はい | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
-H "Authorization: Bearer $ARKVORY_TOKEN"コントローラーを取り消す
DELETE /api/v1/system/fleet/controllers/{id}
アクセス: 管理者 · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
コントローラーを取り消します：そのフリートキーは直ちに拒否されます。再びサイトを管理するには新しいコードでペアリングが必要です。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
id | パス | string (uuid) | はい | — |
レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
例
curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"コントローラーとペアリング
POST /api/v1/system/fleet/enrollment
アクセス: 誰でも（キー不要） · 再試行: 自動的に再試行しない
有効なペアリングコードを一度だけフリートキーと交換します。コントローラーは管理者が確認したフィンガープリントに固定した TLS で呼び出します。キーは一度だけ返され、コントローラーに必要なルートにだけ届きます。
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
code | string | はい | 32文字以内 |
name | string | はい | 1～63文字 |
レスポンス 201
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
key | string | はい | ^afk_[A-Za-z0-9_-]{43}$に一致 |
site | object | はい | — |
site.name | string | はい | — |
site.version | string | はい | — |
レスポンス: 201, 400, 403, 405, 413, 415, 503
例
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
-H "Content-Type: application/json" \
-d '{"code":"<code>","name":"<name>"}'フリートコンソール用にこのサイトを取得
GET HEAD /api/v1/system/topology
アクセス: 管理者 · 再試行: 再試行しても安全（読み取り）
このインストールをフリートの1サイトとして返します（ADR 0077）：名前、バージョン、スキーマと役割、利用可能か・書き込み可能か、HA のコピーとノード、リースに基づく読み取りゲートウェイ、各ミラーとインポートのフェーズ・最終同期・lagChanges（まだ適用されていない元の変更）、更新エージェントの状態とダウンロードキュー。サイトのグローバル管理者かペアリング済みのコントローラーだけが読めます。
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
collectedAt | string (date-time) | はい | — |
site | object | はい | — |
site.name | string | はい | — |
site.version | string | はい | — |
site.schema | integer | はい | 0以上 |
site.role | string | はい | 次のいずれか：api, reader |
health | object | はい | — |
health.available | boolean | はい | — |
health.writable | boolean | はい | — |
health.draining | boolean | はい | — |
replication | object | はい | nullも可 |
replication.copies | integer | はい | 0～16 |
replication.required | integer | はい | 1～16 |
replication.singleCopyUntil | string (date-time) | はい | nullも可 |
replication.node | string | いいえ | 63文字以内 |
replication.profile | string | いいえ | 次のいずれか：ha-2, ha-3 |
replication.peers | objectの配列 | いいえ | 16個以内の要素 |
replication.peers[].name | string | はい | 63文字以内 |
replication.peers[].connected | boolean | はい | — |
replication.peers[].disk | string | はい | 24文字以内 |
replication.peers[].complete | boolean | はい | — |
replication.peers[].witness | boolean | はい | — |
gateways | objectの配列 | はい | 16個以内の要素 |
gateways[].slot | integer | はい | 0以上 |
gateways[].active | boolean | はい | — |
gateways[].expiresAt | string (date-time) | はい | — |
mirrors | objectの配列 | はい | 64個以内の要素 |
mirrors[].repository | string | はい | — |
mirrors[].mode | string | はい | 次のいずれか：mirror, import |
mirrors[].upstream | string | はい | — |
mirrors[].sourceRepository | string | はい | — |
mirrors[].phase | string | はい | — |
mirrors[].errorCode | string | はい | nullも可 |
mirrors[].checkedAt | string (date-time) | はい | nullも可 |
mirrors[].syncedAt | string (date-time) | はい | nullも可 |
mirrors[].lagChanges | string | はい | 10進数字で表した整数（文字列として送信）; nullも可 |
mirrors[].copiedArtifacts | integer | はい | 0以上 |
mirrors[].copiedBytes | string | はい | 10進数字で表した整数（文字列として送信） |
updates | object | はい | nullも可 |
updates.currentVersion | string | はい | — |
updates.latest | string | はい | nullも可 |
updates.phase | string | はい | — |
updates.error | string | はい | nullも可 |
updates.automatic | boolean | はい | — |
updates.heartbeatAt | string (date-time) | はい | — |
downloads | object | はい | — |
downloads.strategy | string | はい | 次のいずれか：ordered, smallest-first, shared |
downloads.sessions | integer | はい | 0以上 |
downloads.active | integer | はい | 0以上 |
downloads.waiting | integer | はい | 0以上 |
downloads.oldestWaitSeconds | integer | はい | 0以上 |
downloads.bytesPerSecond | integer | はい | 0以上 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ダウンロードキューの設定を読む
GET HEAD /api/v1/system/downloads/settings
アクセス: 管理者 · 再試行: 再試行しても安全（読み取り）
変更された値（overrides）、サーバーの環境が定める値（defaults）、キューが現在使っている値（effective）と、変更時に返すリビジョンを返します。problem は保存された設定がこのサーバーに合わない理由を示します。その場合キューは既定値で動作します。
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
revision | integer | はい | 0～9007199254740991 |
overrides | object | はい | — |
overrides.strategy | string | いいえ | 次のいずれか：ordered, smallest-first, shared |
overrides.sessions | integer | いいえ | 1～1024 |
overrides.reserve | integer | いいえ | 0～1023 |
overrides.perPrincipal | integer | いいえ | 1～1024 |
overrides.weights | object | いいえ | — |
overrides.weights.interactive | integer | はい | 1～1000 |
overrides.weights.release | integer | はい | 1～1000 |
overrides.weights.bulk | integer | はい | 1～1000 |
overrides.weights.background | integer | はい | 1～1000 |
overrides.sessionMinBytes | integer | いいえ | 0～9007199254740991 |
overrides.idleSeconds | integer | いいえ | 1～3600 |
overrides.agingMinutes | integer | いいえ | 0～10080 |
overrides.preempt | boolean | いいえ | — |
overrides.rangesPerSession | integer | いいえ | 1～64 |
defaults | object | はい | — |
defaults.strategy | string | はい | 次のいずれか：ordered, smallest-first, shared |
defaults.sessions | integer | はい | 1～1024 |
defaults.reserve | integer | はい | 0～1023 |
defaults.perPrincipal | integer | はい | 1～1024 |
defaults.weights | object | はい | — |
defaults.weights.interactive | integer | はい | 1～1000 |
defaults.weights.release | integer | はい | 1～1000 |
defaults.weights.bulk | integer | はい | 1～1000 |
defaults.weights.background | integer | はい | 1～1000 |
defaults.sessionMinBytes | integer | はい | 0～9007199254740991 |
defaults.idleSeconds | integer | はい | 1～3600 |
defaults.agingMinutes | integer | はい | 0～10080 |
defaults.preempt | boolean | はい | — |
defaults.rangesPerSession | integer | はい | 1～64 |
effective | object | はい | — |
effective.strategy | string | はい | 次のいずれか：ordered, smallest-first, shared |
effective.sessions | integer | はい | 1～1024 |
effective.reserve | integer | はい | 0～1023 |
effective.perPrincipal | integer | はい | 1～1024 |
effective.weights | object | はい | — |
effective.weights.interactive | integer | はい | 1～1000 |
effective.weights.release | integer | はい | 1～1000 |
effective.weights.bulk | integer | はい | 1～1000 |
effective.weights.background | integer | はい | 1～1000 |
effective.sessionMinBytes | integer | はい | 0～9007199254740991 |
effective.idleSeconds | integer | はい | 1～3600 |
effective.agingMinutes | integer | はい | 0～10080 |
effective.preempt | boolean | はい | — |
effective.rangesPerSession | integer | はい | 1～64 |
admission | string | はい | 次のいずれか：sessions, per-request |
updatedAt | string (date-time) | はい | nullも可 |
updatedBy | string | はい | nullも可 |
actor | string | はい | nullも可 |
problem | string | はい | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ダウンロードキューの設定を変更する
PUT /api/v1/system/downloads/settings
アクセス: 管理者 · 再試行: 想定するリビジョンを指定した場合のみ再試行（compare-and-swap）
overrides をサーバーの環境の上に保存し、再起動なしで適用します。新しい判断はすぐにそれに従い、進行中のダウンロードは場所を保ちます。渡した値はそれまでの変更をすべて置き換え、{} で環境の値に戻ります。このサーバーで動作できない設定はフィールド名付きの 400 で拒否され、古い expectedRevision は 409 になります。読み取りゲートウェイは自身の環境を保ちます。
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
expectedRevision | integer | はい | 0～9007199254740991 |
overrides | object | はい | — |
overrides.strategy | string | いいえ | 次のいずれか：ordered, smallest-first, shared |
overrides.sessions | integer | いいえ | 1～1024 |
overrides.reserve | integer | いいえ | 0～1023 |
overrides.perPrincipal | integer | いいえ | 1～1024 |
overrides.weights | object | いいえ | — |
overrides.weights.interactive | integer | はい | 1～1000 |
overrides.weights.release | integer | はい | 1～1000 |
overrides.weights.bulk | integer | はい | 1～1000 |
overrides.weights.background | integer | はい | 1～1000 |
overrides.sessionMinBytes | integer | いいえ | 0～9007199254740991 |
overrides.idleSeconds | integer | いいえ | 1～3600 |
overrides.agingMinutes | integer | いいえ | 0～10080 |
overrides.preempt | boolean | いいえ | — |
overrides.rangesPerSession | integer | いいえ | 1～64 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
revision | integer | はい | 0～9007199254740991 |
overrides | object | はい | — |
overrides.strategy | string | いいえ | 次のいずれか：ordered, smallest-first, shared |
overrides.sessions | integer | いいえ | 1～1024 |
overrides.reserve | integer | いいえ | 0～1023 |
overrides.perPrincipal | integer | いいえ | 1～1024 |
overrides.weights | object | いいえ | — |
overrides.weights.interactive | integer | はい | 1～1000 |
overrides.weights.release | integer | はい | 1～1000 |
overrides.weights.bulk | integer | はい | 1～1000 |
overrides.weights.background | integer | はい | 1～1000 |
overrides.sessionMinBytes | integer | いいえ | 0～9007199254740991 |
overrides.idleSeconds | integer | いいえ | 1～3600 |
overrides.agingMinutes | integer | いいえ | 0～10080 |
overrides.preempt | boolean | いいえ | — |
overrides.rangesPerSession | integer | いいえ | 1～64 |
defaults | object | はい | — |
defaults.strategy | string | はい | 次のいずれか：ordered, smallest-first, shared |
defaults.sessions | integer | はい | 1～1024 |
defaults.reserve | integer | はい | 0～1023 |
defaults.perPrincipal | integer | はい | 1～1024 |
defaults.weights | object | はい | — |
defaults.weights.interactive | integer | はい | 1～1000 |
defaults.weights.release | integer | はい | 1～1000 |
defaults.weights.bulk | integer | はい | 1～1000 |
defaults.weights.background | integer | はい | 1～1000 |
defaults.sessionMinBytes | integer | はい | 0～9007199254740991 |
defaults.idleSeconds | integer | はい | 1～3600 |
defaults.agingMinutes | integer | はい | 0～10080 |
defaults.preempt | boolean | はい | — |
defaults.rangesPerSession | integer | はい | 1～64 |
effective | object | はい | — |
effective.strategy | string | はい | 次のいずれか：ordered, smallest-first, shared |
effective.sessions | integer | はい | 1～1024 |
effective.reserve | integer | はい | 0～1023 |
effective.perPrincipal | integer | はい | 1～1024 |
effective.weights | object | はい | — |
effective.weights.interactive | integer | はい | 1～1000 |
effective.weights.release | integer | はい | 1～1000 |
effective.weights.bulk | integer | はい | 1～1000 |
effective.weights.background | integer | はい | 1～1000 |
effective.sessionMinBytes | integer | はい | 0～9007199254740991 |
effective.idleSeconds | integer | はい | 1～3600 |
effective.agingMinutes | integer | はい | 0～10080 |
effective.preempt | boolean | はい | — |
effective.rangesPerSession | integer | はい | 1～64 |
admission | string | はい | 次のいずれか：sessions, per-request |
updatedAt | string (date-time) | はい | nullも可 |
updatedBy | string | はい | nullも可 |
actor | string | はい | nullも可 |
problem | string | はい | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"overrides":{}}'サイトの変更を読む
GET HEAD /api/v1/system/changes
アクセス: 管理者 · 再試行: 再試行しても安全（読み取り）
サイトのエージェントが報告しているか（agent）、待機中のリクエスト、最新 20 件とその状態（pending、applying、done、または理由付きの failed）を返します。ソースキーがここに現れることはありません。
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
agent | boolean | はい | — |
updating | boolean | はい | — |
blocked | string | はい | 次のいずれか：expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; nullも可 |
pending | object | はい | nullも可 |
pending.id | string (uuid) | はい | — |
pending.kind | string | はい | 次のいずれか：mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
pending.actor | string | はい | 200文字以内 |
pending.requestedAt | string (date-time) | はい | — |
recent | objectの配列 | はい | 20個以内の要素 |
recent[].id | string (uuid) | はい | — |
recent[].digest | string | はい | ^[0-9a-f]{64}$に一致 |
recent[].kind | string | はい | 次のいずれか：mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
recent[].state | string | はい | 次のいずれか：pending, applying, done, failed |
recent[].error | string | はい | 次のいずれか：expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; nullも可 |
recent[].actor | string | はい | 200文字以内 |
recent[].requestedAt | string (date-time) | はい | — |
recent[].finishedAt | string (date-time) | はい | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"サイトの変更をキューに入れる
POST /api/v1/system/changes
アクセス: 管理者 · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
サイトのエージェント向けに変更を 1 つキューに入れます。エージェントは 1 分以内に arkvory configure と cluster-* の検査とロールバック付きで適用します：ミラーまたはインポートの接続、ソースキーの交換、ミラーの切り離し、アクティブな HA ノードの切り替え（ノード名を 2 回入力）、単一コピー書き込みの決定。id はクライアントが選び、繰り返しても再度キューに入りません。key は mirror-attach と mirror-key のソースキーのみで、専用の 0600 ファイルでエージェントに渡り、返されることはありません。202 はキュー投入済みであり、適用済みではありません。
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
id | string (uuid) | はい | — |
change | object | はい | — |
change.kind | string | はい | 次のいずれか：mirror-attach |
change.repository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
change.upstream | string | はい | 255文字以内 |
change.sourceRepository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
change.stages | stringの配列 | いいえ | 1～16個の要素; 各要素：^[a-z0-9][a-z0-9_.-]{0,31}$に一致; nullも可 |
change.repositories | stringの配列 | はい | 1～64個の要素; 各要素：^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
change.node | string | はい | ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$に一致 |
change.confirm | string | はい | ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$に一致 |
change.until | string (date-time) | はい | nullも可 |
change.reason | string | はい | 1～200文字 |
key | string | いいえ | 16～4000文字 |
レスポンス 202
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
id | string (uuid) | はい | — |
レスポンス: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"00000000-0000-4000-8000-000000000000","change":{"kind":"mirror-attach","repository":"<repository>","upstream":"<upstream>","sourceRepository":"<sourceRepository>"}}'リポジトリの変更フィードの取得
GET HEAD /api/v1/repositories/{repository}/changes
アクセス: リポジトリ権限：artifact.list; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
シーケンスafter（既定は0）より後の変更を、コミット順に最大limit件（1〜100、既定は100）返します。各変更には、アクションとアーティファクトが含まれ、ファイルパスとステージについては、そのパスまたはステージがdetailに含まれます。実行者は含まれないため、一覧表示の権限があれば十分です。headはリポジトリの最新のシーケンス、nextは次のページのカーソルで、ページがheadに達した場合はnullです。ミラーは最後に適用したシーケンスを保存し、そこからポーリングします。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
after | クエリ | string | いいえ | 10進数字で表した整数（文字列として送信）; Sequence cursor, default 0 |
limit | クエリ | integer | いいえ | 1～100 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | — |
items[].sequence | string | はい | 10進数字で表した整数（文字列として送信） |
items[].action | string | はい | — |
items[].artifactId | string (uuid) | はい | — |
items[].detail | string | はい | nullも可 |
head | string | はい | 10進数字で表した整数（文字列として送信） |
next | string | はい | 10進数字で表した整数（文字列として送信）; nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ダウンロードリンクの作成
POST /api/v1/repositories/{repository}/artifacts/{id}/links
アクセス: リポジトリ権限：content.read; ファイルキー：read · 再試行: 自動的に再試行しない
キーなしでこの1つのアーティファクトをdownloadArtifactするための、秘密のtoken、APIオリジンからの相対url、expiresAtを返します。ttlSecondsで有効期間を設定します（60秒〜1日、既定は1時間）。トークンはこの応答でのみ表示され、取り消せません。有効期限が切れるかアーティファクトが削除されると使えなくなり、これを通じたダウンロードは作成者の転送制限に計上されます。呼び出し元が保持できる有効なリンクは1000件までで（507 token_limit）、ダウンロードリンクから別のリンクを作成することはできません。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
ttlSeconds | integer | いいえ | 60～86400; 既定値：3600 |
レスポンス 201
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
token | string | はい | ^dtl_[A-Za-z0-9_-]{43}$に一致 |
url | string | はい | — |
expiresAt | string (date-time) | はい | — |
レスポンス: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'