Blob Storage API 快速入门

Blob Storage 用于保存你的文件，通过 CDN 提供公开文件，并为私有文件生成链接。本页使用 curl，带你从 API 密钥开始，完成一次文件上传并获得下载链接。所有套餐都包含存储空间：套餐、价格和常见问题见 Blob Storage。

基础 URL

本参考中的每个端点都相对于：

https://blob.squarecloud.app/v1

身份验证

Blob Storage 在 Authorization 请求头中使用与 Square Cloud API 相同的 API 密钥。上传需要 blob:write scope，列出和下载需要 blob:read，并且该密钥不能限定到特定应用。请在账户安全设置中创建密钥，并保存在环境变量中：

export SQUARECLOUD_API_KEY="your-api-key"

关于 scope 和上传令牌的更多信息，请参阅身份验证。

上传文件

对象上传以 multipart/form-data 接收文件，并在查询参数中接收不含扩展名的文件名：

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}

文件默认是公开的：url 可以直接在浏览器或 <img> 标签中使用。请原样保存 id，因为其他所有路由都需要它。单个请求可接收 512 字节到 100 MB 的文件。更大的文件（最大 10 GiB）请使用分块上传或 S3 网关。

上传私有文件

添加 private=true，文件就不会有公开 URL（url 为 null）：

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'

下载文件

公开文件可通过其 url 下载。对于私有文件，对象下载会签发一个无需凭证即可使用的临时链接并重定向到该链接，因此 curl -L 会直接保存文件：

curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

将 <id> 替换为上传返回的 id。添加 redirect=false 可以以 JSON 形式获取链接并转交给他人。如需可吊销或可设置密码的链接，请创建分享链接。

列出和删除文件

对象列表会分页返回你的文件：

curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

对象删除可删除一个文件，或在一个请求中删除最多 100 个文件：

curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'

出错时

错误以 { "status": "error", "code": "..." } 的形式返回。你最可能首先遇到的是：

代码	HTTP	解决方法
`ACCESS_DENIED`	401	密钥缺失或无法识别。请检查 `Authorization` 请求头。
`PERMISSION_DENIED`	401	账户没有有效套餐，因此无法上传。
`MISSING_SCOPE`	403	密钥缺少 `blob:write` 或 `blob:read`。请创建具有该 scope 的密钥。
`RESOURCE_NOT_ALLOWED`	403	密钥被限定到了特定应用。请使用没有该限制的密钥。
`FILE_TOO_LARGE`	413	文件超过 100 MB。请使用分块上传。

所有代码见错误。

后续步骤

Blob SDK

在 JavaScript 中上传和管理文件，分块上传会自动处理。

S3 兼容性

使用 aws-cli、boto3、rclone 或任意 AWS SDK。

链接与分享

临时链接、分享链接以及各自的适用场景。

从浏览器上传

让访客上传文件，而不暴露你的 API 密钥。

​基础 URL

​身份验证

​上传文件

​上传私有文件

​下载文件

​列出和删除文件

​出错时

​后续步骤