Vodniki

Začni z API-jem Nubbo

Od ničle do prve zahteve v nekaj minutah. Ustvari ključ in začni upravljati svojo shrambo iz lastne kode.

API Nubbo je REST API za delo s tvojimi bucketi iz tvoje kode: datoteke, mape, povezave, zahteve za datoteke, galerije, oznake, projekti in avtomatizacije. V tem vodniku ustvariš ključ in s curl pošlješ prve zahteve.

Kaj dobiš

  • Upravljanje svojega prostora Nubbo iz svojih programov, s ključi, ki vidijo samo to, kar izbereš.
  • Neposredno nalaganje in prenašanje med tvojo kodo in tvojim ponudnikom shrambe.
  • Odzivanje na nove datoteke, nalaganja v zahteve za datoteke in dejavnost s sprožilci.

Preden začneš

Potrebuješ račun Nubbo s paketom Pro ali Ekipe in terminal s curl. V ekipi ključe API ustvarja lastnik ali skrbnik.

1. korak: ustvari ključ

  1. V Nubbo odpri Nastavitve › API (ali Ekipa › API v ekipi) in pritisni Ustvari ključ API.

  2. Vpiši ime in izberi:

    • Dostop: Samo branje ali Branje in pisanje.
    • Obseg: Ves prostor ali Izbrani bucketi in projekti. Ključ vidi samo to, kar izbereš tukaj.
    • Potek: 30 dni, 90 dni, 1 leto ali Brez poteka. Nubbo te opomni 7 dni prej.

    Pritisni Ustvari ključ. Nubbo te prosi za geslo, da potrdi, da si to ti. Če imaš vklopljeno dvostopenjsko preverjanje, te prosi tudi za kodo.

    Okno Ustvari ključ API z dostopom, obsegom in potekom Okno Ustvari ključ API z dostopom, obsegom in potekom
  3. Kopiraj ključ in pritisni Ključ je shranjen. Začne se z nbk_ in v celoti ga vidiš samo zdaj. Hrani ga na strežniku ali v orodju, ki ga bo uporabljalo, nikoli na spletni strani.

    Okno Tvoj ključ API s ključem, pripravljenim za kopiranje Okno Tvoj ključ API s ključem, pripravljenim za kopiranje

2. korak: tvoja prva zahteva

Ključ pošlji v glavi Authorization vsake zahteve. Začni z GET /v1/me, ki ne porabi zahtev:

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

Odgovor vsebuje tvoj prostor, tvoj paket, kvoto meseca in ključ z njegovim dostopom in obsegom. To je izsek:

{
  "workspace": { "id": "…", "name": "Studio Sever", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Moj prvi ključ",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Nato izpiši svoje buckete in datoteke ene mape:

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

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

Seznami vrnejo data in nextCursor. Za naslednjo stran pošlji to vrednost v cursor. Ko je nextCursor enak null, ni ničesar več.

Terminal z zahtevo GET /v1/me in njenim odgovorom Terminal z zahtevo GET /v1/me in njenim odgovorom

3. korak: referenca

V Nastavitve › API pritisni Prikaži dokumentacijo ali odpri api.nubbo.app/v1/docs. Tam je vsak vir s svojimi polji in primeri. Dokument OpenAPI je na api.nubbo.app/v1/openapi.json.

Referenca API Nubbo s primerom v curl Referenca API Nubbo s primerom v curl

Nalaganje in prenašanje

Datoteke ne gredo skozi Nubbo. Če želiš naložiti datoteko, začni nalaganje z POST /v1/buckets/{bucketId}/uploads, pošlji datoteko na vnaprej podpisan naslov, ki ga dobiš, in končaj z POST /v1/uploads/{uploadId}/complete. Za prenos zahtevaj povezavo z POST /v1/files/{fileId}/download-link in datoteko prenesi od svojega ponudnika.

Omejitve

ProEkipe
Zahteve na minuto na ključ60120
Zahteve na mesec50.000100.000 + 10.000 na sedež
Dogodki sprožilcev na mesec20.00050.000 + 5.000 na sedež

Kvota pripada prostoru in se obnovi z vsakim obračunskim obdobjem. GET /v1/me, poizvedbe sprožilcev in odgovori 401, 429 in 5xx se ne štejejo kot zahteve. Vsak dogodek, ki ga sprožilec dostavi, se šteje kot dogodek sprožilca. Vsak odgovor vsebuje glavi X-RateLimit-Remaining in X-Nubbo-Quota-Requests-Remaining, v Nastavitve › API pa vidiš porabo obdobja.

Poraba API v obdobju v nastavitvah Nubbo Poraba API v obdobju v nastavitvah Nubbo

Če gre kaj narobe

  • API_KEY_INVALID, API_KEY_REVOKED ali API_KEY_EXPIRED: ključ ni veljaven, je preklican ali je potekel. Preveri glavo ali ustvari nov ključ.
  • API_PLAN_REQUIRED: prostor ključa nima API-ja. Vključen je v paketa Pro in Ekipe.
  • API_KEY_READ_ONLY: ključ je samo za branje. Ustvari ključ z dostopom Branje in pisanje.
  • API_RATE_LIMITED: preveč zahtev s tem ključem. Počakaj toliko sekund, kot piše v Retry-After, in poskusi znova.
  • API_QUOTA_EXCEEDED: prostor je porabil mesečno omejitev. details.resetsAt pove, kdaj se obnovi.

Vsaka napaka vsebuje requestId. Dodaj ga, če nam pišeš.

Več o API-ju Nubbo. Če ga želiš uporabljati brez pisanja kode, sledi vodniku za Zapier, n8n ali Make. Če ga želiš uporabljati iz svojega AI asistenta, poglej, kako povezati Nubbo s Claude, ChatGPT ali Cursorjem.

Pogosta vprašanja

Kateri paketi vključujejo API?

Pro in Ekipe. S paketom Brezplačno ali Personal zahteve odgovorijo z API_PLAN_REQUIRED.

Ali lahko z API-jem berem šifrirane datoteke?

Ne. Šifrirani elementi se prikažejo brez imena, poti, velikosti in vrste, vsaka sprememba na njih pa je zavrnjena z API_ENCRYPTED_CONTENT.

Kaj se zgodi, če zahtevo ponovim po napaki omrežja?

V zahtevah POST in PATCH pošlji glavo Idempotency-Key. 24 ur ponovitev iste zahteve vrne prvi odgovor in ničesar ne ustvari dvakrat.

Ali se bo API spremenil brez opozorila?

Ne. Sprememba, ki kaj pokvari, pride kot /v2, /v1 pa ostane vsaj 12 mesecev z glavama Deprecation in Sunset.

Viri

Koraki so preverjeni s temi stranmi.