Blob 分块上传初始化

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'myfile',
  filename: 'reads.fastq.gz',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});

const { response: upload } = await response.json();
// persist upload.upload — it is the only handle to this upload

import requests

response = requests.post(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
)
upload = response.json()['response']

{
  "status": "success",
  "response": {
    "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
    "id": "3155597145698959364/myfile-ex30.fastq.gz",
    "name": "myfile",
    "prefix": null,
    "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 205,
      "max_object_size": 1073741824
    }
  }
}

string

必填

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

Chunked Init 用于开启一次分块上传，即针对超过 100 MB 单请求上限、最大 1 GiB 文件的上传流程。它会预留对象的键，并返回一个不透明的 upload 令牌，供你在后续三个调用中携带：分块发送用于发送每个分块，分块完成用于封存对象，分块中止用于取消。服务端不保存会话：该令牌就是上传的全部状态，因此如果上传会跨越页面刷新，请持久化保存它。丢失令牌的客户端将无法取消上传，已存储的分块会一直计入账户 8 个未完成上传的限制，直到服务回收它们为止（约 24 小时）。查询参数契约与对象上传相同，另加 filename：这里没有 multipart 封装，因此存储的扩展名必须来自查询字符串。上传需要付费套餐。

string

必填

表示文件名称的字符串。（不含扩展名）
必须符合 a 到 z、A 到 Z、0 到 9 以及 _ 的模式。（3 到 32 个字符）

string

原始文件名，包含扩展名（例如 reads.fastq.gz）。存储的扩展名由它推导得出，其次回退到 mime_type 参数，最后回退到 bin。

string

表示文件前缀的字符串。
必须符合 a 到 z、A 到 Z、0 到 9 以及 _ 的模式。（3 到 32 个字符）

number

表示文件过期周期的数字，范围为 7 到 1825 天（5 年）。

boolean

如果需要安全哈希，请设为 true。

boolean

如果文件应设为自动下载，请设为 true。

限制

对象大小：最大 1 GiB（1,073,741,824 字节）。
分块大小：最小 5 MB，最大 32 MB（最后一个分块可以更小）。
每个对象的分块数：205（分块编号从 1 到 205）。
每个账户的未完成上传数：8 个并存（TOO_MANY_OPEN_UPLOADS，429）。
速率限制：每 10 秒可开启 5 次，超出后封锁 10 秒。

请从响应中的 chunk 对象读取这些限制，而不要将其硬编码。

响应

string

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

object

显示展开对象

string

不透明的上传令牌。请在该流程后续的每次调用中携带它；它是此次上传的唯一句柄。

string

对象将要存储在其下的 ID（键）。

string

文件的名称。

string

文件将要存储的前缀（未发送时为 null）。

string

对象完成后对外提供服务的公开 CDN URL。

object

分块流程的限制：min_size 和 max_size（分块字节数）、max_parts，以及 max_object_size（总字节数）。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'myfile',
  filename: 'reads.fastq.gz',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});

const { response: upload } = await response.json();
// persist upload.upload — it is the only handle to this upload

import requests

response = requests.post(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
)
upload = response.json()['response']

{
  "status": "success",
  "response": {
    "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
    "id": "3155597145698959364/myfile-ex30.fastq.gz",
    "name": "myfile",
    "prefix": null,
    "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 205,
      "max_object_size": 1073741824
    }
  }
}

故障排查

400 状态码
401 状态码
403 状态码
429 状态码
500 状态码

对象相关

// The provided object name is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_NAME"
}

// The provided object prefix is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_PREFIX"
}

// The provided expiration value for the object is invalid.
// Must be a number ranging from 7 to 1825. (value in days).
{
    "status": "error",
    "code": "INVALID_OBJECT_EXPIRE"
}

// The file extension is malformed or too long.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
{
    "status": "error",
    "code": "BLOCKED_FILE_TYPE"
}

未授权

// 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"
}

存储配额超限

// You have exceeded your storage quota. Delete some files or upgrade your plan.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

速率受限

// Init rate limit reached (5 opens per 10s window, blocked for 10s).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// 8 chunked uploads already open. Complete or abort one first.
{
    "status": "error",
    "code": "TOO_MANY_OPEN_UPLOADS"
}

上传失败

// Failed to open the chunked upload. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

分块发送本文档全面介绍 SquareCloud Blob API 的 PUT /v1/objects/chunked 端点。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'myfile',
  filename: 'reads.fastq.gz',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});

const { response: upload } = await response.json();
// persist upload.upload — it is the only handle to this upload

import requests

response = requests.post(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
)
upload = response.json()['response']

{
  "status": "success",
  "response": {
    "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
    "id": "3155597145698959364/myfile-ex30.fastq.gz",
    "name": "myfile",
    "prefix": null,
    "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 205,
      "max_object_size": 1073741824
    }
  }
}

​限制

​响应

​故障排查

​对象相关

​未授权

​存储配额超限

​速率受限

​上传失败

限制

响应

故障排查

对象相关

未授权

存储配额超限

速率受限

上传失败