开始分块上传

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=dataset&filename=reads.fastq.gz&prefix=genomics&private=true' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'dataset',
  filename: file.name,
  prefix: 'genomics',
  private: 'true',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response: upload } = await res.json();
// persist upload.upload: it is the handle to this upload

import requests

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

{
  "status": "success",
  "response": {
    "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk",
    "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz",
    "private": true,
    "url": null,
    "name": "dataset",
    "prefix": "genomics",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 2048,
      "max_object_size": 10737418240
    }
  }
}

string

必填

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

分块初始化会开启一次分块上传，这是用于超过单请求 100 MB 限制、最大 10 GiB 文件的流程。它会返回一个不透明的 upload 令牌，你需要在后续调用中一直携带它：

初始化

即本路由。保存好 upload 令牌。

发送分块

分块发送，顺序任意，每次最多 6 个。

完成

分块完成会封存文件。或者使用分块中止取消。

服务器端没有会话：令牌就是全部的上传状态，因此如果上传可能跨越页面刷新，请将其持久化。弄丢了？未完成上传会列出未完成的上传及其令牌，分块状态会告诉你哪些分块已经送达。空闲 24 小时的上传会被自动中止。

参数

查询参数与对象上传相同，另外增加了 filename 和 mime_type：这里没有 multipart 封装，因此扩展名必须来自查询参数。需要 blob:write scope，或上传令牌，以及有效计划。

string

必填

文件名，不含扩展名。模式与对象上传相同。

string

原始文件名，包含扩展名。存储的扩展名首先取自它，其次取自 mime_type，最后回退为 bin。

string

仅当 filename 没有扩展名时用于确定扩展名。

string

与对象上传相同。

boolean

与对象上传相同。

string

与对象上传相同。

boolean

与对象上传相同。

boolean

与对象上传相同。

string

与对象上传相同。

boolean

与对象上传相同。

string

与对象上传相同。

string

与对象上传相同。

限制

文件大小：最大 10 GiB（10,737,418,240 字节），如果规则或上传令牌设置了更小的限制则以其为准。
分块大小：最小 5 MB（5,242,880 字节），最大 32 MB（33,554,432 字节）。最后一个分块可以更小。
每个文件的分块数：最多 2048 个。
每个账户的未完成上传数：32 个，包括通过 S3 网关开启的上传（TOO_MANY_OPEN_UPLOADS，429）。
速率限制：每 10 秒 5 次开启。
已超出内置存储配额的账户无法开启上传（STORAGE_QUOTA_EXCEEDED）。

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

响应

string

成功为 “success”，否则为 “error”。

object

显示展开对象

string

不透明的上传令牌。在该流程的每个后续调用中都要发送它。

string

文件完成后将拥有的 id。

boolean

文件是否将为私有。

string | null

文件将拥有的公开 URL，私有时为 null。

ISO 8601

文件将被删除的时间。仅当文件会过期时出现。

string

请求中发送的名称。

string

前缀，仅当请求中发送了前缀时出现。

object

本次上传的限制：min_size 和 max_size（分块字节数）、max_parts，以及 max_object_size（文件字节数）。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=dataset&filename=reads.fastq.gz&prefix=genomics&private=true' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'dataset',
  filename: file.name,
  prefix: 'genomics',
  private: 'true',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response: upload } = await res.json();
// persist upload.upload: it is the handle to this upload

import requests

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

{
  "status": "success",
  "response": {
    "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk",
    "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz",
    "private": true,
    "url": null,
    "name": "dataset",
    "prefix": "genomics",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 2048,
      "max_object_size": 10737418240
    }
  }
}

错误

代码	HTTP	触发情况
`INVALID_OBJECT_*` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	某个参数无效，与对象上传相同。
`INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	扩展名格式错误、被屏蔽，或规则或令牌不允许该扩展名。
`PERMISSION_DENIED`	401	账户没有有效计划。
`UPLOAD_TOKEN_USED`	401	上传令牌已没有剩余使用次数。已过期的令牌返回 `ACCESS_DENIED`。
`STORAGE_QUOTA_EXCEEDED`	403	账户已超出其内置存储配额。
`PREFIX_NOT_ALLOWED`	403	上传令牌绑定的是另一个前缀。
`UPGRADE_REQUIRED`	403	某个选项需要更高级别的计划。
`TOO_MANY_OPEN_UPLOADS`	429	账户已有 32 个未完成的上传。请完成或中止其中一个。
`RATE_LIMITED`	429	10 秒内超过 5 次开启。
`UPLOAD_FAILED`	500	无法开启上传。请重试。
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	存储暂时不可用。请重试。

入门

对象

分块上传

账户

分享链接

S3

参数

限制

响应

错误

相关内容

​参数

​限制

​响应

​错误

​相关内容

参数

限制

响应

错误

相关内容