ステージとプロモーション
アーティファクトのステージ（例：release）、リポジトリ間のプロモーション、ステージからバージョンへの解決。
このグループの操作と、それぞれのアクセスルール、再試行ルール、パラメーター、レスポンスです。すべてのリクエストにはキーを付けます：Authorization: Bearer <key>（「認証」を参照）。
操作
アーティファクトのステージの一覧表示
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/stages
アクセス: リポジトリ権限：artifact.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
公開済みアーティファクトの現在のプロモーションステージ（最大16件）を、追加された時刻、実行者、コメントとともに返します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 16個以内の要素 |
items[].artifactId | string (uuid) | はい | — |
items[].stage | string | はい | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
items[].promotedAt | string (date-time) | はい | — |
items[].actor | string | はい | — |
items[].comment | string | はい | 1024文字以内; nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトへのステージの追加
PUT /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
アクセス: リポジトリ権限：artifact.promote, artifact.read; ファイルキー：read, write · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
公開済みアーティファクトにstage（英小文字、数字、_.-からなる1〜32文字で、先頭は英字または数字）を付け、必要に応じて最大1024文字のcommentを添えて、プロモーションジャーナルにイベントを記録します。アーティファクトがすでに持っているステージを追加しても何も変わらず、元の時刻が維持されます。そのため、同じバージョンを再度プロモートするとき（order=promotedを使ったロールバックのため）は、先にそのステージを削除してください。アーティファクトのステージは最大16個です（409 stage_limit）。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
stage | パス | string | はい | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
comment | string | いいえ | 1024文字以内; nullも可 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
artifactId | string (uuid) | はい | — |
stage | string | はい | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
promotedAt | string (date-time) | はい | — |
actor | string | はい | — |
comment | string | はい | 1024文字以内; nullも可 |
レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'アーティファクトからのステージの削除
DELETE /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
アクセス: リポジトリ権限：artifact.promote, artifact.read; ファイルキー：read, write · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
公開済みアーティファクトからstageを削除し、プロモーションジャーナルにイベントを記録します。アーティファクトが持っていないステージを削除した場合も成功します。このステージによるパッケージの解決では、そのアーティファクトはただちに選ばれなくなります。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
stage | パス | string | はい | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
例
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトのプロモーション履歴の一覧表示
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/promotions
アクセス: リポジトリ権限：artifact.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
1つのアーティファクトのジャーナルを古いものから返します。内容は、ステージの追加と削除、他のリポジトリへの、または他のリポジトリからのプロモーションで、相手側のアーティファクト、実行者、コメント、時刻が含まれます。ページにはlimit件のイベント（1〜100、既定は50）が含まれ、続きはafterにnextを設定して取得します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
after | クエリ | string | いいえ | 10進数字で表した整数（文字列として送信） |
limit | クエリ | string | いいえ | 10進数字で表した整数（文字列として送信）; At most 100. |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 100個以内の要素 |
items[].sequence | string | はい | 10進数字で表した整数（文字列として送信） |
items[].repository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
items[].artifactId | string (uuid) | はい | — |
items[].action | string | はい | 次のいずれか：stage.added, stage.removed, promoted, received |
items[].stage | string | はい | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致; nullも可 |
items[].mode | string | はい | 次のいずれか：copy, move, null; nullも可 |
items[].peerRepository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致; nullも可 |
items[].peerArtifactId | string (uuid) | はい | nullも可 |
items[].actor | string | はい | — |
items[].comment | string | はい | 1024文字以内; nullも可 |
items[].occurredAt | string (date-time) | はい | — |
next | string | はい | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"アーティファクトの別のリポジトリへのプロモート
POST /api/v1/repositories/{repository}/artifacts/{id}/promote
アクセス: リポジトリ権限：artifact.read, content.read; ファイルキー：read · 再試行: 再試行しても安全：同じリクエストは同じ効果になる
バイト列を再送せずに、アーティファクトをtargetに公開します。必要に応じてstagesとcommentを指定できます。呼び出し元にはtargetでのartifact.promoteも必要です。modeがcopy（既定）の場合はコピー元を残します。moveではこちらのリポジトリでもartifact.promoteが必要で、同じトランザクション内でコピー元を論理削除してそのステージを引き継ぎ、コピー元を削除できない場合は409で拒否されます。応答は201とコピーです。繰り返すと同じコピーが200で返り、宛先にすでにこのパッケージバージョンがある場合は、SHA-256が一致すればそのアーティファクトを返し、一致しなければ409 version_existsになります。ビルドの添付ファイルとファイルパスは引き継がれません。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
id | パス | string (uuid) | はい | — |
リクエスト本文 (application/json)
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
target | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
mode | string | いいえ | 次のいずれか：copy, move |
stages | stringの配列 | いいえ | 16個以内の要素; 要素の重複なし; 各要素：^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
comment | string | いいえ | 1024文字以内; nullも可 |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
repository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
artifactId | string (uuid) | はい | — |
sourceRepository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
sourceArtifactId | string (uuid) | はい | — |
mode | string | はい | 次のいずれか：copy, move |
created | boolean | はい | — |
stages | stringの配列 | はい | 16個以内の要素; 要素の重複なし; 各要素：^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
レスポンス: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promote" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"target":"<target>"}'ステージを持つアーティファクトの一覧表示
GET HEAD /api/v1/repositories/{repository}/stages
アクセス: リポジトリ権限：artifact.list; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
リポジトリのステージエントリ（アーティファクト、ステージ、時刻、実行者、コメント）を、アーティファクトとステージの順に列挙します。stageのみ、またはids（カンマ区切りの1〜100個のID。たとえばパッケージの1ページ分のステージを一度に表示する場合に使用）に含まれるアーティファクトのみに絞り込むこともできます。ページにはlimit件のエントリ（1〜100、既定は100）が含まれ、続きはafterにnext（<artifactId>/<stage>）を設定して取得します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
stage | クエリ | string | いいえ | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
after | クエリ | string | いいえ | — |
limit | クエリ | string | いいえ | 10進数字で表した整数（文字列として送信）; At most 100. |
ids | クエリ | string | いいえ | 3699文字以内; Up to 100 comma-separated artifact ids. |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 100個以内の要素 |
items[].artifactId | string (uuid) | はい | — |
items[].stage | string | はい | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
items[].promotedAt | string (date-time) | はい | — |
items[].actor | string | はい | — |
items[].comment | string | はい | 1024文字以内; nullも可 |
next | string | はい | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"リポジトリのプロモーションジャーナルの取得
GET HEAD /api/v1/repositories/{repository}/promotions
アクセス: リポジトリ権限：artifact.list; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
リポジトリ内のすべてのアーティファクトのステージとプロモーションのイベントを、CI/CDがポーリングできるように古いものから返します。対象は、ステージの追加と削除、別のリポジトリへのプロモート、別のリポジトリからの受け取りです。ページにはlimit件のイベント（1〜100、既定は50）が含まれ、最後のsequenceを保存して、afterにnextを設定して続きを取得します。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
after | クエリ | string | いいえ | 10進数字で表した整数（文字列として送信） |
limit | クエリ | string | いいえ | 10進数字で表した整数（文字列として送信）; At most 100. |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
items | objectの配列 | はい | 100個以内の要素 |
items[].sequence | string | はい | 10進数字で表した整数（文字列として送信） |
items[].repository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
items[].artifactId | string (uuid) | はい | — |
items[].action | string | はい | 次のいずれか：stage.added, stage.removed, promoted, received |
items[].stage | string | はい | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致; nullも可 |
items[].mode | string | はい | 次のいずれか：copy, move, null; nullも可 |
items[].peerRepository | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致; nullも可 |
items[].peerArtifactId | string (uuid) | はい | nullも可 |
items[].actor | string | はい | — |
items[].comment | string | はい | 1024文字以内; nullも可 |
items[].occurredAt | string (date-time) | はい | — |
next | string | はい | nullも可 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"パッケージバージョンの解決
GET HEAD /api/v1/repositories/{repository}/packages/resolve
アクセス: リポジトリ権限：package.read; ファイルキー：read · 再試行: 再試行しても安全（読み取り）
downloadPackageContentと同じルールで登録済みのUPackバージョンを1つ選び、バイト列なしで返します。内容は、バージョン、アーティファクトID、SHA-256、サイズ、公開時刻、現在のステージです。nameは必須で、groupの既定はルートグループです。正確なversionまたはSemVerのrangeで選択でき、必要に応じてstage、prerelease=true、order=promoted（stageが必要）も指定できます。versionとrangeのどちらも指定しない場合は、最も高い安定版バージョンになります。一致するものがなければ404です。そのバージョンに固定したままにするには、結果をアーティファクトIDでダウンロードしてください。
パラメーター
| 名前 | 場所 | 型 | 必須 | ルール |
|---|---|---|---|---|
repository | パス | string | はい | ^[a-z0-9][a-z0-9_-]{0,63}$に一致 |
group | クエリ | string | いいえ | 128文字以内 |
name | クエリ | string | はい | 1～128文字 |
version | クエリ | string | いいえ | 128文字以内; Exact version; excludes range. |
range | クエリ | string | いいえ | 256文字以内; SemVer range: 1.2.3, ^1.2, ~1.2.3, 1.x, >=1.0.0 <2.0.0, a || b. |
stage | クエリ | string | いいえ | ^[a-z0-9][a-z0-9_.-]{0,31}$に一致; Only versions promoted to this stage. |
prerelease | クエリ | string | いいえ | 次のいずれか：true, false; Include prereleases. |
order | クエリ | string | いいえ | 次のいずれか：version, promoted; promoted picks the most recently staged version and requires stage. |
レスポンス 200
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
group | string | はい | — |
name | string | はい | — |
version | string | はい | — |
artifactId | string (uuid) | はい | — |
sha256 | string | はい | SHA-256：小文字の16進数字64桁 |
size | string | はい | 10進数字で表した整数（文字列として送信） |
publishedAt | string (date-time) | はい | — |
stagedAt | string (date-time) | はい | nullも可 |
stages | stringの配列 | はい | 16個以内の要素; 要素の重複なし; 各要素：^[a-z0-9][a-z0-9_.-]{0,31}$に一致 |
レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507
例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/packages/resolve?name=$NAME" \
-H "Authorization: Bearer $ARKVORY_TOKEN"