Blob 分块上传发送

curl --request PUT \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN&part=1' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@./chunk-1.bin'

const chunk = file.slice(0, 16 * 1024 * 1024); // first 16 MB

const params = new URLSearchParams({ upload: uploadToken, part: '1' });

const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'PUT',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/octet-stream',
  },
  body: chunk,
});

import requests

with open('./bigfile.bin', 'rb') as f:
    chunk = f.read(16 * 1024 * 1024)

response = requests.put(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/octet-stream'},
    params={'upload': upload_token, 'part': 1},
    data=chunk,
)

{
  "status": "success",
  "response": {
    "part": 1,
    "size": 16777216,
    "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
  }
}

string

必填

你账户的 API 密钥。你可以在账户设置中找到它。

Chunked Part 用于发送通过分块初始化开启的上传中的一个分块。请求体是该分块的原始字节，而不是 multipart/form-data。分块编号从 1 到 max_parts（205），并且可以按任意顺序发送；失败的分块只需用相同编号重新发送即可，由于分块是幂等的，重发是安全的。除最后一个分块外，每个分块必须在 5 MB 到 32 MB 之间；最后一个可以更小。最多同时并行发送 6 个分块：第 7 个在途分块会返回 TOO_MANY_CONCURRENT_CHUNKS，此时请等待某个分块完成后再重试该分块。在 6 个分块并行的情况下，对浏览器而言 16 MB 的分块大小是一个不错的默认值。该路由不计入账户级 API 配额（plan.rate），因此一次耗时较长的上传不会耗尽你在平台其他部分的 API 配额。它自身的限流器允许每 10 秒发送 60 个分块，超出后封锁 10 秒。

string

必填

由分块初始化返回的不透明 upload 令牌。

number

必填

分块编号，从 1 到 205。分块可以按任意顺序发送。

binary

必填

分块的原始字节（Content-Type: application/octet-stream）。不是 multipart/form-data。

响应

string

指示调用是否成功。成功为 “success”，否则为 “error”。

object

显示展开对象

number

已存储的分块编号。

number

已存储分块的大小，单位为字节。

string

该分块的存储 ETag。仅供参考：完成时会从存储端读回分块列表，因此你永远不需要把它传回。

curl --request PUT \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN&part=1' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@./chunk-1.bin'

const chunk = file.slice(0, 16 * 1024 * 1024); // first 16 MB

const params = new URLSearchParams({ upload: uploadToken, part: '1' });

const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'PUT',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/octet-stream',
  },
  body: chunk,
});

import requests

with open('./bigfile.bin', 'rb') as f:
    chunk = f.read(16 * 1024 * 1024)

response = requests.put(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/octet-stream'},
    params={'upload': upload_token, 'part': 1},
    data=chunk,
)

{
  "status": "success",
  "response": {
    "part": 1,
    "size": 16777216,
    "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
  }
}

故障排查

分块相关

// The upload token is missing, malformed, or does not belong to your account.
{
    "status": "error",
    "code": "INVALID_UPLOAD_TOKEN"
}

// The part number must be an integer between 1 and 205.
{
    "status": "error",
    "code": "INVALID_CHUNK_PART"
}

// The chunk body was empty.
{
    "status": "error",
    "code": "EMPTY_CHUNK"
}

未授权

// The API key is missing or invalid. Set a valid key in the Authorization header.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

// The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
{
    "status": "error",
    "code": "PERMISSION_DENIED"
}

未找到

// The upload was already completed, aborted, or expired.
{
    "status": "error",
    "code": "UPLOAD_NOT_FOUND"
}

载荷过大

// Each chunk accepts up to 32 MB.
{
    "status": "error",
    "code": "CHUNK_TOO_LARGE"
}

速率受限

// Part rate limit reached (60 parts per 10s window, blocked for 10s).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// At most 6 chunks may be in flight at a time. Wait for one to finish, then retry this part.
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_CHUNKS"
}

上传失败

// Failed to upload the chunk. Retry this part.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

分块完成本文档全面介绍 SquareCloud Blob API 的 PATCH /v1/objects/chunked 端点。

curl --request PUT \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN&part=1' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@./chunk-1.bin'

const chunk = file.slice(0, 16 * 1024 * 1024); // first 16 MB

const params = new URLSearchParams({ upload: uploadToken, part: '1' });

const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'PUT',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/octet-stream',
  },
  body: chunk,
});

import requests

with open('./bigfile.bin', 'rb') as f:
    chunk = f.read(16 * 1024 * 1024)

response = requests.put(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/octet-stream'},
    params={'upload': upload_token, 'part': 1},
    data=chunk,
)

{
  "status": "success",
  "response": {
    "part": 1,
    "size": 16777216,
    "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
  }
}

​响应

​故障排查

​分块相关

​未授权

​未找到

​载荷过大

​速率受限

​上传失败

响应

故障排查

分块相关

未授权

未找到

载荷过大

速率受限

上传失败