指南

開始使用 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 標頭。

資料來源

步驟已對照以下頁面核實。