上传
可续传的上传：创建上传会话，整体或分片发送字节，完成上传，并跟踪其完成任务。
本组中的操作及其访问规则、重试规则、参数和响应。每个请求都需携带密钥：Authorization: Bearer <密钥>（参见“身份验证”）。
操作
列出上传已接收的分片
GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts
访问: 仓库权限：upload.read; 文件密钥：write · 重试: 可安全重试（读取）
返回 partBytes（创建上传时为该上传确定的分片大小：8 MiB，若文件需要超过 10 000 个分片则加倍；只有最后一个分片更短），以及已存储的分片及其序号、大小和 SHA-256。续传中断的分片上传之前先读取它，然后只用 putUploadPart 发送缺失的分片。只有上传的创建者能看到它；其他人得到 404。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
partBytes | integer | 否 | 8388608–1073741824; 除最后一个分片外，每个分片都是这个大小。 |
items | 数组（object） | 否 | — |
items[].index | integer | 是 | 0–9999 |
items[].size | integer | 是 | 1–1073741824 |
items[].sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"上传一个分片
PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}
访问: 仓库权限：upload.write; 文件密钥：write · 重试: 先重新读取上传状态，再做决定
将请求体存储为待完成分片上传的第 index 个分片（从 0 开始）；其长度必须恰好等于 partBytes（来自 listUploadParts），最后一个分片则为剩余字节数，且 X-Content-SHA256 必须是这些字节小写十六进制的 SHA-256，否则返回 422。分片可以按任意顺序到达，但同一个上传同一时间只处理一个请求（并发的请求会得到 503 busy）；用相同的哈希重复发送分片是安全的，对已存储的序号发送不同的哈希则返回 409 part_mismatch。所有分片都存储完毕后，调用 completeUpload 或 enqueueCompletion。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
index | 路径 | integer | 是 | 0–9999 |
X-Content-SHA256 | 标头 | string | 是 | SHA-256：64 位小写十六进制数字 |
请求正文 (application/octet-stream)
响应: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts/$INDEX" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "X-Content-SHA256: $X_CONTENT_SHA256" \
-H "Content-Type: application/octet-stream" \
--data-binary @file在后台完成上传
POST /api/v1/repositories/{repository}/uploads/{id}/complete-async
访问: 仓库权限：upload.complete; 文件密钥：write · 重试: 先重新读取任务状态，再做决定
将待完成上传的完成操作交给工作进程（worker）服务排队处理，而不是在请求中执行，并立即返回 202 和该作业；用 getCompletionJob 跟踪它。对同一个上传再次调用会返回同一个作业，因瞬时原因失败的作业会重新排队。作业已排队不代表制品已发布：只有 completed 才表示已发布。如果上传不再处于待完成状态，返回 409 upload_state；当调用方已有 100 个未完成的作业或服务器已有 10 000 个时，返回 507 queue_full。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
响应 202
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
uploadId | string (uuid) | 是 | — |
repository | string | 是 | — |
owner | string | 是 | — |
status | string | 是 | 取值之一：queued, running, completed, failed |
generation | integer | 是 | 0–2147483647 |
attempts | integer | 是 | 不小于 0 |
credentialId | string (uuid) | 否 | 可选的发起操作的托管密钥 ID；绝不包含其机密值。 |
errorCode | string | 是 | 可以为 null |
响应: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
-H "Authorization: Bearer $ARKVORY_TOKEN"获取完成作业
GET HEAD /api/v1/jobs/{id}
访问: 仓库权限：job.read; 文件密钥：write · 重试: 可安全重试（读取）
返回通过 enqueueCompletion 排队的完成作业的状态：queued、running、completed（上传已发布）或带有 errorCode 的 failed，以及尝试次数。工作进程最多尝试五次，间隔逐渐变长；诸如 integrity_mismatch 之类的错误会立即失败。只有该作业的创建者能看到它；其他人得到 404。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
id | 路径 | string (uuid) | 是 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
uploadId | string (uuid) | 是 | — |
repository | string | 是 | — |
owner | string | 是 | — |
status | string | 是 | 取值之一：queued, running, completed, failed |
generation | integer | 是 | 0–2147483647 |
attempts | integer | 是 | 不小于 0 |
credentialId | string (uuid) | 否 | 可选的发起操作的托管密钥 ID；绝不包含其机密值。 |
errorCode | string | 是 | 可以为 null |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"创建上传会话
POST /api/v1/repositories/{repository}/uploads
访问: 仓库权限：upload.create; 文件密钥：write · 重试: 使用相同的 Idempotency-Key 可安全重试
为一个文件预留上传，该文件由 name、size（十进制字符串）、sha256 以及可选的 labels 和 metadata 描述；返回 201，包含会话（pending，有效期 7 天）及其 Location。必须提供 Idempotency-Key（1–128 个字母、数字和 _.:-）：相同的键和相同的描述返回同一个会话，描述不同则返回 409 idempotency_mismatch。大小会立即按仓库配额和服务器容量预留（507）。然后用 putUploadContent 整体发送字节，或用 putUploadPart 分片发送并以 completeUpload 结束。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
Idempotency-Key | 标头 | string | 是 | 最多 128 个字符 |
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
name | string | 是 | 1–240 个字符 |
size | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
labels | 数组（string） | 否 | 最多 32 项; 每项：最多 64 个字符 |
metadata | 映射（string） | 否 | 最多 32 个条目 |
响应 201
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
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 | 是 | 用十进制数字表示的整数，以字符串形式发送 |
descriptor.sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
descriptor.labels | 数组（string） | 否 | 最多 32 项; 每项：最多 64 个字符 |
descriptor.metadata | 映射（string） | 否 | 最多 32 个条目 |
响应: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","size":"1024","sha256":"<sha256: SHA-256>"}'获取上传
GET HEAD /api/v1/repositories/{repository}/uploads/{id}
访问: 仓库权限：upload.read; 文件密钥：write · 重试: 可安全重试（读取）
返回会话及其 status（pending；发布后为 available；cancelled）、过期时间和已声明的描述符。如果 putUploadContent 或 completeUpload 的响应丢失，请先读取此项：available 表示制品已以相同的 ID 发布。只有上传的创建者能看到它；其他人得到 404。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
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 | 是 | 用十进制数字表示的整数，以字符串形式发送 |
descriptor.sha256 | string | 是 | SHA-256：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/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"取消上传
DELETE /api/v1/repositories/{repository}/uploads/{id}
访问: 仓库权限：upload.cancel; 文件密钥：write · 重试: 先重新读取上传状态，再做决定
取消待完成的上传，并返回状态为 cancelled 的上传；已发布的上传无法取消（409 upload_state）。已接收的字节会立即被隐藏，但仍按配额保留，直到仓库的在线物理清理（setCleanup，默认关闭）在宽限期后将其删除。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
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 | 是 | 用十进制数字表示的整数，以字符串形式发送 |
descriptor.sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
descriptor.labels | 数组（string） | 否 | 最多 32 项; 每项：最多 64 个字符 |
descriptor.metadata | 映射（string） | 否 | 最多 32 个条目 |
响应: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"在一次请求中上传整个文件
PUT /api/v1/repositories/{repository}/uploads/{id}/content
访问: 仓库权限：upload.write, upload.complete; 文件密钥：write · 重试: 先重新读取上传状态，再做决定
将请求体作为待完成上传的完整内容以流式写入，按声明的大小和 SHA-256 进行校验（不一致时返回 422），然后发布制品；响应为状态是 available 的上传。中断的请求没有可续传的内容：用 getUpload 读取该上传，然后从头开始重新发送整个文件。已有分片的上传不能使用此操作（409 upload_state）；此外，单个请求必须在服务器的上传期限（默认 30 分钟）内完成，因此大文件请使用分片上传。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
请求正文 (application/octet-stream)
响应 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 | 是 | 用十进制数字表示的整数，以字符串形式发送 |
descriptor.sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
descriptor.labels | 数组（string） | 否 | 最多 32 项; 每项：最多 64 个字符 |
descriptor.metadata | 映射（string） | 否 | 最多 32 个条目 |
响应: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @file完成上传
POST /api/v1/repositories/{repository}/uploads/{id}/complete
访问: 仓库权限：upload.complete; 文件密钥：write · 重试: 先重新读取上传状态，再做决定
按顺序组装已存储的分片，按声明的大小和 SHA-256 校验整个文件，然后发布制品；返回状态为 available 的上传。对已发布的上传再次调用会返回相同的结果，因此也可用来恢复响应丢失的完成操作。缺少分片返回 409 parts_incomplete，内容不匹配返回 422；对于请求可能超时的超大文件，请改用 enqueueCompletion。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
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 | 是 | 用十进制数字表示的整数，以字符串形式发送 |
descriptor.sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
descriptor.labels | 数组（string） | 否 | 最多 32 项; 每项：最多 64 个字符 |
descriptor.metadata | 映射（string） | 否 | 最多 32 个条目 |
响应: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
-H "Authorization: Bearer $ARKVORY_TOKEN"