指南

开始使用 Nubbo API

从零开始到发出第一个请求,只需要几分钟。创建一个 API 密钥,开始通过你自己的代码来管理存储空间。

Nubbo API 是一个 REST API,让你用自己的代码操作存储桶:文件、文件夹、链接、文件请求、相册、标签、项目和自动化。在本指南中,你将创建一个密钥,并用 curl 发出最初的几个请求。

你将获得什么

  • 通过你的程序管理 Nubbo 空间,密钥只能看到你选择的内容。
  • 在你的代码和存储服务商之间直接上传和下载。
  • 通过触发器响应新文件、文件请求上传和活动。

开始之前

你需要一个使用 Pro 或团队套餐的 Nubbo 账号,以及一个装有 curl 的终端。在团队中,API 密钥由所有者或管理员创建。

第 1 步:创建密钥

  1. 在 Nubbo 中打开 设置 › API(在团队中为 团队 › API),点击 创建 API 密钥。

  2. 输入名称并选择:

    • 权限:只读 或 读写。
    • 范围:整个空间 或 选定的存储桶和项目。密钥只能看到你在这里选择的内容。
    • 有效期:30 天、90 天、1 年或 永不过期。Nubbo 会提前 7 天提醒你。

    点击 创建密钥。Nubbo 会要求输入密码,确认是你本人。 如果启用了双重验证,还需要输入验证码。

    创建 API 密钥窗口,显示权限、范围和有效期 创建 API 密钥窗口,显示权限、范围和有效期
  3. 复制密钥并点击 我已保存。密钥以 nbk_ 开头,这是你唯一一次看到完整密钥。请把它保存在服务器或将要使用它的工具中,切勿放在网页里。

    你的 API 密钥窗口,密钥可供复制 你的 API 密钥窗口,密钥可供复制

第 2 步:第一个请求

在每个请求的 Authorization 请求头中携带密钥。先从 GET /v1/me 开始,它不计入请求数:

curl https://api.nubbo.app/v1/me \
  -H "Authorization: Bearer nbk_your_key"

响应包含你的空间、套餐、本月配额,以及密钥的权限和范围。以下是节选:

{
  "workspace": { "id": "…", "name": "北方工作室", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "我的第一个密钥",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

然后列出你的存储桶和某个文件夹中的文件:

curl https://api.nubbo.app/v1/buckets \
  -H "Authorization: Bearer nbk_your_key"

curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=invoices/" \
  -H "Authorization: Bearer nbk_your_key"

列表返回 data 和 nextCursor。要获取下一页,在 cursor 中发送该值。当 nextCursor 为 null 时,就没有更多内容了。

终端中的 GET /v1/me 请求及其响应 终端中的 GET /v1/me 请求及其响应

第 3 步:参考文档

在 设置 › API 中点击 查看文档,或打开 api.nubbo.app/v1/docs。那里列出了每个资源及其字段和示例。OpenAPI 文档位于 api.nubbo.app/v1/openapi.json。

Nubbo API 参考文档中的 curl 示例 Nubbo API 参考文档中的 curl 示例

上传和下载

文件不经过 Nubbo。要上传文件,先用 POST /v1/buckets/{bucketId}/uploads 发起上传,把文件发送到返回的预签名地址,再用 POST /v1/uploads/{uploadId}/complete 完成。要下载文件,用 POST /v1/files/{fileId}/download-link 获取链接,然后从你的服务商下载。

限额

Pro团队
每个密钥每分钟请求数60120
每月请求数50,000100,000 + 每个席位 10,000
每月触发事件数20,00050,000 + 每个席位 5,000

配额属于空间,并在每个计费周期重置。GET /v1/me、触发器的轮询以及 401、429 和 5xx 响应不计为请求。触发器每投递一个事件,计为一个触发事件。每个响应都带有 X-RateLimit-Remaining 和 X-Nubbo-Quota-Requests-Remaining 响应头,设置 › API 会显示本周期的用量。

Nubbo 设置中本周期的 API 用量 Nubbo 设置中本周期的 API 用量

如果出现问题

  • API_KEY_INVALID、API_KEY_REVOKED 或 API_KEY_EXPIRED:密钥无效、已被撤销或已过期。检查请求头或创建新密钥。
  • API_PLAN_REQUIRED:密钥所属空间不包含 API。API 包含在 Pro 和团队套餐中。
  • API_KEY_READ_ONLY:密钥为只读。请创建一个读写密钥。
  • API_RATE_LIMITED:此密钥的请求过多。等待 Retry-After 中的秒数后再试。
  • API_QUOTA_EXCEEDED:空间已用完本月限额。details.resetsAt 会告诉你何时重置。

每个错误都带有 requestId。联系我们时请附上它。

了解更多关于 Nubbo API 的信息。如果不想写代码,请按照 Zapier、n8n 或 Make 指南操作。如果想在 AI 助手中使用,请查看如何 将 Nubbo 连接到 Claude、ChatGPT 或 Cursor。

常见问题

哪些套餐包含 API?

Pro 和团队。使用免费或 Personal 套餐时,请求会返回 API_PLAN_REQUIRED。

我能用 API 读取加密文件吗?

不能。加密内容显示时没有名称、路径、大小或类型,对它的任何更改都会被拒绝并返回 API_ENCRYPTED_CONTENT。

如果网络故障后我重复发送请求,会怎样?

在 POST 和 PATCH 请求中发送 Idempotency-Key 请求头。24 小时内重复同一请求会返回第一次的响应,不会重复创建任何内容。

API 会在不通知的情况下变更吗?

不会。不兼容的变更会以 /v2 发布,/v1 至少保留 12 个月,并带有 Deprecation 和 Sunset 响应头。

来源

步骤已对照以下页面核实。