列出 Blob Storage 中的文件

GET

objects

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \
  --header 'Authorization: YOUR_API_KEY'

let cursor;
do {
  const params = new URLSearchParams({ prefix: 'images/', limit: '1000' });
  if (cursor) params.set('cursor', cursor);

  const res = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  for (const object of response.objects) console.log(object.id, object.size);
  cursor = response.continuationToken;
} while (cursor);

import requests

cursor = None
while True:
    params = {'prefix': 'images/', 'limit': 1000}
    if cursor:
        params['cursor'] = cursor
    response = requests.get(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params=params,
    ).json()['response']
    for obj in response['objects']:
        print(obj['id'], obj['size'])
    cursor = response.get('continuationToken')
    if not cursor:
        break

{
  "status": "success",
  "response": {
    "objects": [
      {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
      },
      {
        "id": "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "size": 90466,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": true,
        "url": null,
        "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\""
      }
    ],
    "folders": ["images/icons/"],
    "continuationToken": "Q7mZp2Xk9LwR4vTn8sHd1c"
  }
}

string

必填

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

对象列表会枚举存储在你账户下的文件，可以按前缀和可见性进行过滤，并使用游标分页，而不是一次性返回所有内容。可用它来构建文件浏览器、确认上传已完成，或将你自己的记录与 Blob Storage 中保存的内容进行核对。需要 blob:read scope。每组参数对应的分页结果会缓存 30 分钟，而你自己的上传和删除操作会清除该缓存，因此它们会立即显示出来。结果的顺序不作保证。在还有更多对象时，某一页包含的对象数可能少于 limit：请持续请求，直到 continuationToken 不再出现。

参数

string

只返回路径以该字符串开头的文件（例如 images/ 或 images/2026-）。字母、数字、_、.、- 和 /，最多 256 个字符。

string

只能是 /。将下一个 / 之下的文件归入 folders，而不是逐个列出，类似于目录列表。

boolean

true 只列出私有文件，false 只列出公开文件。省略则两者都列出。

number

默认值:"1000"

每页的最大条目数，范围为 1 到 1000。

string

上一页的 continuationToken。也接受 continuationToken 作为参数名。

速率限制

每 30 秒 30 次请求，超出后会被短暂封禁（RATE_LIMITED，429）。

响应

string

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

object

显示展开对象

array

显示展开对象

string

对象 id。请将其视为不透明值。

integer

文件大小，单位为字节。

ISO 8601

文件的存储时间。

ISO 8601

文件将被删除的时间。不会过期的文件省略此字段。

boolean

文件是否为私有。

string | null

公开 URL，私有文件为 null。

string

文件的 ETag。内容改变时它也会改变。

string[]

prefix 下的文件夹，每个都以 / 结尾。仅在 delimiter=/ 时出现。

string

将其作为 cursor 传回以获取下一页。最后一页不包含此字段。

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \
  --header 'Authorization: YOUR_API_KEY'

let cursor;
do {
  const params = new URLSearchParams({ prefix: 'images/', limit: '1000' });
  if (cursor) params.set('cursor', cursor);

  const res = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  for (const object of response.objects) console.log(object.id, object.size);
  cursor = response.continuationToken;
} while (cursor);

import requests

cursor = None
while True:
    params = {'prefix': 'images/', 'limit': 1000}
    if cursor:
        params['cursor'] = cursor
    response = requests.get(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params=params,
    ).json()['response']
    for obj in response['objects']:
        print(obj['id'], obj['size'])
    cursor = response.get('continuationToken')
    if not cursor:
        break

{
  "status": "success",
  "response": {
    "objects": [
      {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
      },
      {
        "id": "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "size": 90466,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": true,
        "url": null,
        "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\""
      }
    ],
    "folders": ["images/icons/"],
    "continuationToken": "Q7mZp2Xk9LwR4vTn8sHd1c"
  }
}

错误

代码	HTTP	触发情况
`INVALID_OBJECT_PREFIX`	400	`prefix` 含有模式之外的字符或包含 `..`。
`INVALID_DELIMITER`	400	`delimiter` 不是 `/`。
`INVALID_OBJECT_PRIVATE`	400	`private` 不是 `true` 或 `false`。
`INVALID_LIMIT`	400	`limit` 不是 1 到 1000 之间的整数。
`INVALID_CONTINUATION_TOKEN`	400	`cursor`（或 `continuationToken`）格式错误或已失效。请不带游标重新开始。
`RATE_LIMITED`	429	30 秒内超过 30 次请求。

相关内容

Blob SDK：blob.list()、blob.listPage()

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \
  --header 'Authorization: YOUR_API_KEY'

let cursor;
do {
  const params = new URLSearchParams({ prefix: 'images/', limit: '1000' });
  if (cursor) params.set('cursor', cursor);

  const res = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  for (const object of response.objects) console.log(object.id, object.size);
  cursor = response.continuationToken;
} while (cursor);

import requests

cursor = None
while True:
    params = {'prefix': 'images/', 'limit': 1000}
    if cursor:
        params['cursor'] = cursor
    response = requests.get(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params=params,
    ).json()['response']
    for obj in response['objects']:
        print(obj['id'], obj['size'])
    cursor = response.get('continuationToken')
    if not cursor:
        break

{
  "status": "success",
  "response": {
    "objects": [
      {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
      },
      {
        "id": "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "size": 90466,
        "created_at": "2026-09-25T12:00:00.000Z",
        "private": true,
        "url": null,
        "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\""
      }
    ],
    "folders": ["images/icons/"],
    "continuationToken": "Q7mZp2Xk9LwR4vTn8sHd1c"
  }
}

入门

对象

分块上传

账户

分享链接

S3

列出 Blob Storage 中的文件

参数

速率限制

响应

错误

相关内容

​参数

​速率限制

​响应

​错误

​相关内容

参数

速率限制

响应

错误

相关内容