阶段与晋级
制品的阶段（例如 release）、仓库之间的晋级，以及将阶段解析为版本。
本组中的操作及其访问规则、重试规则、参数和响应。每个请求都需携带密钥：Authorization: Bearer <密钥>（参见“身份验证”）。
操作
列出制品的阶段
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 · 重试: 可安全重试（读取）
按从旧到新的顺序返回单个制品的日志：添加和移除的阶段、向其他仓库的晋级以及来自其他仓库的晋级（含对端制品）、操作者、备注和时间。每页包含 limit 个事件（1–100，默认 50）；将 after 设为 next 即可继续。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
after | 查询 | string | 否 | 用十进制数字表示的整数，以字符串形式发送 |
limit | 查询 | string | 否 | 用十进制数字表示的整数，以字符串形式发送; At most 100. |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 是 | 最多 100 项 |
items[].sequence | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
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；调用方在目标仓库中还需要 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，例如用于一次显示一页包的阶段）。每页包含 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 | 否 | 用十进制数字表示的整数，以字符串形式发送; 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 | 否 | 用十进制数字表示的整数，以字符串形式发送 |
limit | 查询 | string | 否 | 用十进制数字表示的整数，以字符串形式发送; At most 100. |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 是 | 最多 100 项 |
items[].sequence | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
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 版本，并在不返回字节的情况下返回它：版本、制品 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：64 位小写十六进制数字 |
size | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
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"