Blob 对象上传 - Square Cloud

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

string

必填

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

Object Post 用于将单个文件上传到 Square Cloud Blob Storage，并返回一个基于 CDN 的 URL，可直接嵌入或分享，无需自行配置存储桶或管理 ACL。它支撑着平台上托管应用的附件、生成的导出文件以及用户上传的媒体内容。存储的扩展名来自你在 multipart 部分中发送的文件名（其次回退到声明的 MIME 类型，最后回退到 bin），因此请始终发送真实的文件名。实际上几乎任何文件类型都可以接受；只有可执行文件和安装程序会被拒绝。可以为对象设置 7 到 1825 天（5 年）之间的自动过期时间，超过该时间后对象将不再对外提供。单次请求接受 512 字节到 100 MB 的文件，这是 Cloudflare 边缘所接受的最大请求体。更大的文件（最大 1 GiB）请走分块上传流程。文件上传完成后，可使用对象列表浏览，使用对象删除移除，或使用账户统计跟踪相对于套餐配额的用量。

file

必填

使用 FormData（multipart/form-data）。每次请求仅限一个文件。
请发送真实的文件名：存储的扩展名由它推导得出。

string

必填

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

string

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

number

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

boolean

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

boolean

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

速率限制与并发

上传需要付费套餐。

每个账户最多可同时进行 4 次上传。当已有 4 次上传仍在进行时再启动一次上传，将返回 TOO_MANY_CONCURRENT_UPLOADS（429）。
Hobby 和 Standard 套餐还额外限制为每秒 1 次上传（RATE_LIMITED，429）。Pro 和 Enterprise 套餐不受此每秒限制约束。

出于安全考虑，浏览器会内联渲染的格式（.html、.svg、.xml、.xhtml 及类似格式）始终以下载方式提供（作为 application/octet-stream 提供），而不会被渲染。设置 auto_download=true 会对任意文件类型强制应用同样的下载行为。

文件类型

实际上几乎任何扩展名都可以接受，包括没有注册 MIME 类型的格式（.bam、.vcf、.fasta、.fastq、.parquet、.h5、.npy 等）。不再存在 MIME 白名单。

存储的扩展名由 multipart 部分中发送的文件名推导得出，其次回退到声明的 MIME 类型，最后回退到 bin。
复合压缩后缀会被保留：reads.fastq.gz 存储为 .fastq.gz，而不是 .gz。
对外提供时的 Content-Type 由服务器端根据扩展名推导。未知格式以 application/octet-stream 提供，因此会以下载而非渲染的方式呈现。
可执行文件和安装程序会被拒绝为 BLOCKED_FILE_TYPE：exe、msi、dll、bat、cmd、com、scr、cpl、pif、hta、vbs、vbe、jse、wsf、wsh、msc、reg、lnk、sys、drv、ps1、apk、xpi。

响应

string

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

object

显示展开对象

string

已上传文件的 ID。

string

已上传文件的名称。

string

文件所存储的前缀（回显自 prefix 查询参数；未发送时省略）。

number

已上传文件的大小，单位为字节。

string

已上传文件的公开 CDN URL：https://public-blob.squarecloud.dev/<user_id>/<key>，其中 key 的格式为 [prefix/]name[_hash][-exN].ext（哈希和过期后缀仅在使用时出现；扩展名由上传的文件名推导得出）。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

故障排查

对象相关

// 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 provided security hash boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_OBJECT_SECURITY_HASH"
}

// The provided auto-download boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

文件相关

单次请求最大接受 100 MB。最大 1 GiB 的文件请使用分块上传流程。

// The provided file is invalid.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// 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 file size is too small (< 512 bytes).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

未授权

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

无效的内容类型

// This route only accepts multipart/form-data requests with exactly one file.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

载荷过大

单次请求最大接受 100 MB。最大 1 GiB 的文件请使用分块上传流程。

// A single request accepts up to 100 MB. Use /v1/objects/chunked for files up to 1 GiB.
{
    "status": "error",
    "code": "FILE_TOO_LARGE"
}

触发速率限制

// Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// Too many simultaneous uploads (max 4 in progress at a time per account).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

上传失败

// Failed to upload object to storage. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

对象删除本文档全面概述了 SquareCloud Blob API 的 DELETE /v1/objects endpoint。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

​速率限制与并发

​文件类型

​响应

​故障排查

​对象相关

​文件相关

​未授权

​存储配额超限

​无效的内容类型

​载荷过大

​触发速率限制

​上传失败

速率限制与并发

文件类型

响应

故障排查

对象相关

文件相关

未授权

存储配额超限

无效的内容类型

载荷过大

触发速率限制

上传失败