Blob Storage API 身份验证

Blob Storage 在 Authorization 请求头中接受两种凭证：

Authorization: <api_key>

Blob SDK（@squarecloud/blob）会为你发送凭据，并封装了本参考中的每一个路由。

Scope

API key 携带 scope。Blob Storage 读取其中两个：

Scope	路由
`blob:read`	对象列表、对象信息、对象下载、账户统计、获取设置、分享列表
`blob:write`	对象上传、对象更新、对象复制、对象删除、所有分块上传路由、更新设置、上传令牌、创建分享、删除分享
任一	S3 凭证：仅当 key 拥有 `blob:write` 时，它返回的密钥对才能写入

缺少路由所需 scope 的 key 会收到 403 MISSING_SCOPE。限定于特定应用的 key 无权访问 Blob Storage，会收到 403 RESOURCE_NOT_ALLOWED。

为每个集成分配单独的 key，只赋予它所需的 scope。只负责分发文件的后端需要 blob:read；只负责上传的任务需要 blob:write。

上传令牌只在对象上传和分块上传路由上被接受。其他任何路由都会返回 403 UPLOAD_TOKEN_NOT_ALLOWED。令牌会锁定签发时选定的名称、前缀、可见性、大小和文件类型，并在过期、使用次数用尽或签发它的 API key 被撤销时失效。

S3 工具不会直接发送 API key。它们使用由 API key 派生的访问密钥对对请求进行签名（SigV4）：请从 S3 凭证获取该密钥对，并阅读 S3 兼容性。

错误响应遵循 { "status": "error", "code": "SOME_CODE" } 格式，有时会附带解释具体情况的 message。请根据 code 分支处理，绝不要依赖 message。完整列表见错误。

{
    "status": "error",
    "code": "RATE_LIMITED"
}

任何 Blob 路由也都可能返回以下错误：

代码	HTTP	含义
`ACCESS_DENIED`	401	凭证缺失或无法识别（已撤销、已重新生成或已过期）。
`MISSING_SCOPE`	403	API key 缺少该路由所需的 scope。
`RESOURCE_NOT_ALLOWED`	403	API key 限定于特定应用，无法使用 Blob Storage。
`UPLOAD_TOKEN_NOT_ALLOWED`	403	上传令牌被发送到了非上传路由。
`RATE_LIMITED`	429	已达到某项限制：该路由自身的限制、你所在计划的账户级 API 预算，或该 IP 发送了过多无效凭证，已被短暂封禁。请等待后重试。
`ROUTE_NOT_FOUND` / `NOT_FOUND`	404	请求的路由不存在。
`INTERNAL_SERVER_ERROR`	500	意外的内部故障。请稍后重试。

了解 Square Cloud API 的限制与约束。