分块上传
Blob 分块上传完成
本文档全面介绍 SquareCloud Blob API 的 PATCH /v1/objects/chunked 端点。
curl --request PATCH \
--url 'https://blob.squarecloud.app/v1/objects/chunked' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{ "upload": "UPLOAD_TOKEN" }'
const response = await fetch('https://blob.squarecloud.app/v1/objects/chunked', {
method: 'PATCH',
headers: {
Authorization: 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ upload: uploadToken }),
});
import requests
response = requests.patch(
'https://blob.squarecloud.app/v1/objects/chunked',
headers={'Authorization': 'YOUR_API_KEY'},
json={'upload': upload_token},
)
{
"status": "success",
"response": {
"id": "3155597145698959364/myfile-ex30.fastq.gz",
"size": 734003200,
"parts": 22,
"url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz"
}
}
Chunked Complete 用于封存通过分块初始化开启的上传：已存储的分块会被组装成最终对象，并在其公开 URL 上可用。你不需要发送任何 ETag 或分块列表，只需发送
upload 令牌；分块列表会从存储端读回，而存储端本身就是哪些分块已落地的权威数据源。
有两种失败情形会刻意让上传保持开启状态，以便你修复问题后重试 PATCH，而不必重新上传最多 1 GiB 的数据：STORAGE_QUOTA_EXCEEDED（释放空间后重试）和 CHUNK_TOO_SMALL（重新发送有问题的分块后重试）。而 FILE_TOO_SMALL 和 FILE_TOO_LARGE 则会直接中止上传。
速率限制为每 10 秒 5 次完成操作，因此多个并行上传可以同时完成。
string
必填
由分块初始化返回的不透明
upload 令牌。{ "upload": "UPLOAD_TOKEN" }
响应
string
指示调用是否成功。成功为 “success”，否则为 “error”。
curl --request PATCH \
--url 'https://blob.squarecloud.app/v1/objects/chunked' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{ "upload": "UPLOAD_TOKEN" }'
const response = await fetch('https://blob.squarecloud.app/v1/objects/chunked', {
method: 'PATCH',
headers: {
Authorization: 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ upload: uploadToken }),
});
import requests
response = requests.patch(
'https://blob.squarecloud.app/v1/objects/chunked',
headers={'Authorization': 'YOUR_API_KEY'},
json={'upload': upload_token},
)
{
"status": "success",
"response": {
"id": "3155597145698959364/myfile-ex30.fastq.gz",
"size": 734003200,
"parts": 22,
"url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz"
}
}
故障排查
- 400 状态码
- 401 状态码
- 403 状态码
- 404 状态码
- 413 状态码
- 429 状态码
- 500 状态码
上传相关
// The upload token is missing, malformed, or does not belong to your account.
{
"status": "error",
"code": "INVALID_UPLOAD_TOKEN"
}
// The upload has no stored chunks to assemble.
{
"status": "error",
"code": "NO_CHUNKS_UPLOADED"
}
// A chunk other than the last is below 5 MB. The upload stays open:
// re-send the offending parts, then retry the PATCH.
{
"status": "error",
"code": "CHUNK_TOO_SMALL"
}
// The assembled object is below 512 bytes. The upload is aborted.
{
"status": "error",
"code": "FILE_TOO_SMALL"
}
未授权
// The API key is missing or invalid. Set a valid key in the Authorization header.
{
"status": "error",
"code": "ACCESS_DENIED"
}
存储配额超限
// The account filled up while the parts were uploading. The upload is
// LEFT OPEN: free space (or upgrade) and retry the PATCH, or abort it
// with DELETE /v1/objects/chunked.
{
"status": "error",
"code": "STORAGE_QUOTA_EXCEEDED"
}
未找到
// The upload was already completed, aborted, or expired.
{
"status": "error",
"code": "UPLOAD_NOT_FOUND"
}
载荷过大
// The assembled object exceeds 1 GiB. The upload is aborted.
{
"status": "error",
"code": "FILE_TOO_LARGE"
}
速率受限
// Complete rate limit reached (5 requests per 10s window, blocked for 10s).
{
"status": "error",
"code": "RATE_LIMITED"
}
上传失败
// Failed to assemble or register the object. If the message says to start
// a new upload, the uploadId was consumed: open a new upload and send the
// file again. Otherwise, retry the PATCH.
{
"status": "error",
"code": "UPLOAD_FAILED"
}
⌘I
curl --request PATCH \
--url 'https://blob.squarecloud.app/v1/objects/chunked' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{ "upload": "UPLOAD_TOKEN" }'
const response = await fetch('https://blob.squarecloud.app/v1/objects/chunked', {
method: 'PATCH',
headers: {
Authorization: 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ upload: uploadToken }),
});
import requests
response = requests.patch(
'https://blob.squarecloud.app/v1/objects/chunked',
headers={'Authorization': 'YOUR_API_KEY'},
json={'upload': upload_token},
)
{
"status": "success",
"response": {
"id": "3155597145698959364/myfile-ex30.fastq.gz",
"size": 734003200,
"parts": 22,
"url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz"
}
}