Hướng dẫn

Bắt đầu với API của Nubbo

Từ con số 0 đến yêu cầu đầu tiên chỉ trong vài phút. Tạo khóa và bắt đầu quản lý bộ nhớ lưu trữ ngay từ mã của bạn.

API của Nubbo là một API REST để làm việc với bucket từ mã của riêng bạn: tệp, thư mục, liên kết, yêu cầu tệp, thư viện ảnh, nhãn, dự án và tự động hóa. Trong hướng dẫn này, bạn tạo một khóa và gửi những yêu cầu đầu tiên bằng curl.

Bạn nhận được gì

  • Quản lý không gian Nubbo từ chương trình của bạn, với các khóa chỉ thấy những gì bạn chọn.
  • Tải lên và tải xuống trực tiếp giữa mã của bạn và nhà cung cấp lưu trữ.
  • Phản ứng với tệp mới, lượt tải lên vào yêu cầu tệp và hoạt động bằng các trigger.

Trước khi bắt đầu

Bạn cần một tài khoản Nubbo dùng gói Pro hoặc Nhóm và một terminal có curl. Trong một nhóm, khóa API do chủ sở hữu hoặc quản trị viên tạo.

Bước 1: tạo khóa

  1. Trong Nubbo, mở Cài đặt › API (hoặc Nhóm › API trong một nhóm) và nhấn Tạo khóa API.

  2. Đặt tên rồi chọn:

    • Quyền: Chỉ đọc hoặc Đọc và ghi.
    • Phạm vi: Toàn bộ không gian hoặc Bucket và dự án đã chọn. Khóa chỉ thấy những gì bạn chọn ở đây.
    • Thời hạn: 30 ngày, 90 ngày, 1 năm hoặc Không hết hạn. Nubbo nhắc bạn trước 7 ngày.

    Nhấn Tạo khóa. Nubbo hỏi mật khẩu để xác nhận đó là bạn. Nếu bạn bật xác thực hai yếu tố, Nubbo cũng hỏi mã.

    Cửa sổ Tạo khóa API với quyền, phạm vi và thời hạn Cửa sổ Tạo khóa API với quyền, phạm vi và thời hạn
  3. Sao chép khóa và nhấn Tôi đã lưu khóa. Khóa bắt đầu bằng nbk_ và đây là lần duy nhất bạn thấy toàn bộ khóa. Hãy giữ nó trên máy chủ hoặc trong công cụ sẽ dùng nó, không bao giờ đặt trong trang web.

    Cửa sổ Khóa API của bạn với khóa sẵn sàng để sao chép Cửa sổ Khóa API của bạn với khóa sẵn sàng để sao chép

Bước 2: yêu cầu đầu tiên

Gửi khóa trong header Authorization của mỗi yêu cầu. Hãy bắt đầu với GET /v1/me, yêu cầu này không bị tính:

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

Phản hồi cho biết không gian, gói của bạn, hạn mức của tháng và khóa cùng quyền và phạm vi của nó. Đây là một đoạn trích:

{
  "workspace": { "id": "…", "name": "Studio Phương Bắc", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Khóa đầu tiên của tôi",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Sau đó, liệt kê bucket và các tệp trong một thư mục:

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

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

Các danh sách trả về data và nextCursor. Để lấy trang tiếp theo, gửi giá trị đó trong cursor. Khi nextCursor là null, không còn gì nữa.

Terminal với yêu cầu GET /v1/me và phản hồi của nó Terminal với yêu cầu GET /v1/me và phản hồi của nó

Bước 3: tài liệu tham khảo

Trong Cài đặt › API, nhấn Xem tài liệu, hoặc mở api.nubbo.app/v1/docs. Ở đó có từng tài nguyên với các trường và ví dụ. Tài liệu OpenAPI nằm tại api.nubbo.app/v1/openapi.json.

Tài liệu tham khảo API của Nubbo với ví dụ curl Tài liệu tham khảo API của Nubbo với ví dụ curl

Tải lên và tải xuống

Tệp không đi qua Nubbo. Để tải một tệp lên, bắt đầu lượt tải lên bằng POST /v1/buckets/{bucketId}/uploads, gửi tệp tới địa chỉ đã ký sẵn được trả về và hoàn tất bằng POST /v1/uploads/{uploadId}/complete. Để tải xuống, yêu cầu một liên kết bằng POST /v1/files/{fileId}/download-link và tải tệp từ nhà cung cấp của bạn.

Giới hạn

ProNhóm
Yêu cầu mỗi phút cho mỗi khóa60120
Yêu cầu mỗi tháng50.000100.000 + 10.000 mỗi chỗ
Sự kiện trigger mỗi tháng20.00050.000 + 5.000 mỗi chỗ

Hạn mức thuộc về không gian và được làm mới theo mỗi kỳ thanh toán. GET /v1/me, các lần trigger kiểm tra và các phản hồi 401, 429 và 5xx không được tính là yêu cầu. Mỗi sự kiện mà trigger gửi đi được tính là một sự kiện. Mỗi phản hồi đều có các header X-RateLimit-Remaining và X-Nubbo-Quota-Requests-Remaining, và Cài đặt › API hiển thị mức sử dụng của kỳ.

Mức sử dụng API của kỳ trong cài đặt Nubbo Mức sử dụng API của kỳ trong cài đặt Nubbo

Nếu có sự cố

  • API_KEY_INVALID, API_KEY_REVOKED hoặc API_KEY_EXPIRED: khóa không hợp lệ, đã bị thu hồi hoặc đã hết hạn. Kiểm tra header hoặc tạo khóa khác.
  • API_PLAN_REQUIRED: không gian của khóa không có API. API có trong gói Pro và Nhóm.
  • API_KEY_READ_ONLY: khóa chỉ đọc. Hãy tạo một khóa với Đọc và ghi.
  • API_RATE_LIMITED: quá nhiều yêu cầu với khóa này. Chờ số giây trong Retry-After rồi thử lại.
  • API_QUOTA_EXCEEDED: không gian đã dùng hết giới hạn của tháng. details.resetsAt cho biết khi nào hạn mức được làm mới.

Mỗi lỗi đều có một requestId. Hãy gửi kèm nếu bạn liên hệ với chúng tôi.

Tìm hiểu thêm về API của Nubbo. Để dùng API mà không cần viết mã, hãy làm theo hướng dẫn Zapier, n8n hoặc Make. Để dùng từ trợ lý AI, hãy xem cách kết nối Nubbo với Claude, ChatGPT hoặc Cursor.

Câu hỏi thường gặp

Những gói nào có API?

Pro và Nhóm. Với gói Miễn phí hoặc Personal, các yêu cầu trả về API_PLAN_REQUIRED.

Tôi có thể đọc tệp đã mã hóa bằng API không?

Không. Nội dung đã mã hóa hiển thị không có tên, đường dẫn, kích thước hay loại, và mọi thay đổi trên nội dung đó đều bị từ chối với API_ENCRYPTED_CONTENT.

Điều gì xảy ra nếu tôi gửi lại yêu cầu sau lỗi mạng?

Gửi header Idempotency-Key trong các yêu cầu POST và PATCH. Trong 24 giờ, gửi lại cùng một yêu cầu sẽ trả về phản hồi đầu tiên và không tạo gì hai lần.

API có thay đổi mà không báo trước không?

Không. Thay đổi phá vỡ tương thích sẽ ra mắt dưới dạng /v2, còn /v1 được giữ ít nhất 12 tháng, kèm các header Deprecation và Sunset.

Nguồn

Các bước đã được kiểm tra theo những trang này.