路径文件

通过仓库中的路径访问的文件：修订版本、历史记录、恢复，以及通过单个请求处理的原始文件。

本组中的操作及其访问规则、重试规则、参数和响应。每个请求都需携带密钥：Authorization: Bearer <密钥>（参见“身份验证”）。

操作

按前缀列出文件路径

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

示例

bash

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 · 重试: 可安全重试（读取）

按 UTF-8 字节顺序返回以 prefix（按字面匹配；为空则表示全部）开头的当前文件路径，每项包含当前修订版本和制品 ID。每页包含 limit 项（1–100，默认 50）；将 after 设为不透明的 next 即可继续。分页不是快照：请求之间发生变化的路径可能以较新的修订版本出现，或被漏掉，直到下一轮遍历。

参数

名称	位置	类型	必需	规则
`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

示例

bash

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 下载字节，或把该修订版本作为 expectedRevision 传给 setAsset。

参数

名称	位置	类型	必需	规则
`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

示例

bash

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。早期的修订版本保留在历史记录中，其制品也因此不会被删除。若要一次请求同时存储字节并命名，请使用 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

示例

bash

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 的修订版本，每页 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; before 游标，不含该项；到末尾时为 null

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

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

示例

bash

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）

为 path 添加一个指向 sourceRevision 所对应制品的新修订版本；不会复制任何内容，也不会移除任何修订版本。expectedRevision 必须是当前修订版本（至少为 1），否则返回 409 revision_mismatch——因此重复一次已成功的恢复会得到 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

示例

bash

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。每次请求都会重新解析路径，因此续传时请把 If-Range 设为返回的 ETag：路径已指向别处后，返回的是完整的新文件，而不是新旧混合的内容。downloadRawFile 做同样的事，只是路径位于 URL 中。

参数

名称	位置	类型	必需	规则
`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

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

一次请求上传文件到指定路径

PUT /api/v1/repositories/{repository}/raw/{assetPath}

访问: 仓库权限：upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; 文件密钥：write · 重试: 可安全重试：相同的请求效果相同

将任意媒体类型的请求体存储为 URL 中路径的新修订版本，适用于脚本和 CI（curl -T）；响应为 201，包含路径、修订版本和制品。带有 X-Checksum-Sha256 和 Content-Length 时，字节会直接以流式写入存储并被校验；没有它们时，则先暂存并计算哈希（请求体与给定的校验和不一致时返回 422）。与当前修订版本字节相同的内容不会新增修订版本，并返回 200 和 created: false；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	是	用十进制数字表示的整数，以字符串形式发送
`artifact.sha256`	string	是	SHA-256：64 位小写十六进制数字

响应: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507

示例

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file

按 URL 路径下载文件

GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}

访问: 仓库权限：content.read; 文件密钥：read · 重试: 可安全重试（读取）

像 downloadArtifact 一样以流式返回 URL 中路径的当前修订版本，支持 Range、If-Range、If-None-Match、HEAD，并用 X-Arkvory-Artifact-Id 给出制品。每次请求都会重新解析路径，因此续传时请把 If-Range 设为返回的 ETag，或按 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

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

路径文件 ​

操作 ​

按前缀列出文件路径 ​

分页列出文件路径 ​

获取文件路径的当前修订版本 ​

将文件路径指向制品 ​

列出文件路径的修订版本 ​

获取文件路径的某个修订版本 ​

恢复文件路径的早期修订版本 ​

按路径下载文件 ​

一次请求上传文件到指定路径 ​

按 URL 路径下载文件 ​

路径文件

操作

按前缀列出文件路径

分页列出文件路径

获取文件路径的当前修订版本

将文件路径指向制品

列出文件路径的修订版本

获取文件路径的某个修订版本

恢复文件路径的早期修订版本

按路径下载文件

一次请求上传文件到指定路径

按 URL 路径下载文件