Útmutatók

Első lépések a Nubbo API-val

A nulláról az első kérésig néhány perc alatt. Hozz létre egy kulcsot, és kezeld a tárhelyed a saját kódodból.

A Nubbo API egy REST API, amellyel a saját kódodból dolgozhatsz a bucketjeiddel: fájlok, mappák, linkek, fájlkérések, galériák, címkék, projektek és automatizálások. Ebben az útmutatóban létrehozol egy kulcsot, és curllal elküldöd az első kéréseidet.

Mit kapsz

  • A programjaidból kezelheted a Nubbo-teredet, olyan kulcsokkal, amelyek csak azt látják, amit kiválasztasz.
  • Közvetlen feltöltés és letöltés a kódod és a tárhelyszolgáltatód között.
  • Eseményindítókkal reagálhatsz új fájlokra, fájlkérésekbe érkező feltöltésekre és tevékenységre.

Mielőtt elkezdenéd

Kell egy Nubbo-fiók Pro vagy Csapatok csomaggal és egy terminál curllal. Csapatban az API-kulcsokat a tulajdonos vagy egy adminisztrátor hozza létre.

1. lépés: hozz létre egy kulcsot

  1. A Nubbóban nyisd meg a Beállítások › API részt (csapatban a Csapat › API részt), és kattints az API-kulcs létrehozása gombra.

  2. Adj neki nevet, és válaszd ki:

    • Hozzáférés: Csak olvasás vagy Olvasás és írás.
    • Hatókör: A teljes tér vagy Kiválasztott bucketek és projektek. A kulcs csak azt látja, amit itt kiválasztasz.
    • Lejárat: 30 nap, 90 nap, 1 év vagy Nem jár le. A Nubbo 7 nappal előtte figyelmeztet.

    Kattints a Kulcs létrehozása gombra. A Nubbo a jelszavadat kéri, hogy megerősítse, hogy te vagy. Ha be van kapcsolva a kétlépcsős ellenőrzés, a kódot is kéri.

    Az API-kulcs létrehozása ablak a hozzáféréssel, a hatókörrel és a lejárattal Az API-kulcs létrehozása ablak a hozzáféréssel, a hatókörrel és a lejárattal
  3. Másold ki a kulcsot, és kattints az Elmentettem gombra. nbk_ előtaggal kezdődik, és csak most látod teljes egészében. Tárold a szerveren vagy abban az eszközben, amely használni fogja, soha ne egy weboldalon.

    Az API-kulcsod ablak a másolásra kész kulccsal Az API-kulcsod ablak a másolásra kész kulccsal

2. lépés: az első kérésed

Küldd a kulcsot minden kérés Authorization fejlécében. Kezdd a GET /v1/me kéréssel, amely nem fogyaszt kéréseket:

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

A válasz tartalmazza a teredet, a csomagodat, a havi kvótát és a kulcsot a hozzáférésével és a hatókörével. Ez egy részlet:

{
  "workspace": { "id": "…", "name": "Északi Stúdió", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Az első kulcsom",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Ezután listázd a bucketjeidet és egy mappa fájljait:

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

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

A listák data és nextCursor mezőt adnak vissza. A következő oldalhoz küldd el ezt az értéket a cursor paraméterben. Ha a nextCursor értéke null, nincs több.

Terminál a GET /v1/me kéréssel és a válaszával Terminál a GET /v1/me kéréssel és a válaszával

3. lépés: a referencia

A Beállítások › API részben kattints a Dokumentáció megtekintése gombra, vagy nyisd meg az api.nubbo.app/v1/docs oldalt. Ott minden erőforrás megtalálható a mezőivel és példákkal. Az OpenAPI-dokumentum az api.nubbo.app/v1/openapi.json címen érhető el.

A Nubbo API referenciája a curl példával A Nubbo API referenciája a curl példával

Feltöltés és letöltés

A fájlok nem mennek át a Nubbón. Feltöltéshez kérd a feltöltést a POST /v1/buckets/{bucketId}/uploads kéréssel, küldd a fájlt a visszakapott előre aláírt címre, és zárd le a POST /v1/uploads/{uploadId}/complete kéréssel. Letöltéshez kérj linket a POST /v1/files/{fileId}/download-link kéréssel, és töltsd le a fájlt a szolgáltatódtól.

Korlátok

ProCsapatok
Kérés percenként kulcsonként60120
Kérés havonta50 000100 000 + 10 000 helyenként
Eseményindító-esemény havonta20 00050 000 + 5 000 helyenként

A kvóta a téré, és minden számlázási időszakkal megújul. A GET /v1/me, az eseményindítók lekérdezései és a 401, 429 és 5xx válaszok nem számítanak kérésnek. Minden esemény, amelyet egy eseményindító kézbesít, eseménynek számít. Minden válasz tartalmazza az X-RateLimit-Remaining és az X-Nubbo-Quota-Requests-Remaining fejlécet, a Beállítások › API részben pedig látod az időszak használatát.

Az időszak API-használata a Nubbo beállításaiban Az időszak API-használata a Nubbo beállításaiban

Ha valami nem működik

  • API_KEY_INVALID, API_KEY_REVOKED vagy API_KEY_EXPIRED: a kulcs érvénytelen, vissza lett vonva vagy lejárt. Ellenőrizd a fejlécet, vagy hozz létre egy új kulcsot.
  • API_PLAN_REQUIRED: a kulcs terében nincs API. A Pro és a Csapatok csomagban érhető el.
  • API_KEY_READ_ONLY: a kulcs csak olvasható. Hozz létre egyet Olvasás és írás hozzáféréssel.
  • API_RATE_LIMITED: túl sok kérés ezzel a kulccsal. Várj a Retry-After szerinti másodpercig, és próbáld újra.
  • API_QUOTA_EXCEEDED: a tér elhasználta a havi keretét. A details.resetsAt megmondja, mikor újul meg.

Minden hiba tartalmaz egy requestId értéket. Add meg, ha írsz nekünk.

Többet erről: a Nubbo API. Kódírás nélküli használathoz kövesd a Zapier, az n8n vagy a Make útmutatóját. Ha az AI-asszisztensedből használnád, nézd meg, hogyan kapcsolhatod össze a Nubbót a Claude-dal, a ChatGPT-vel vagy a Cursorral.

Gyakori kérdések

Mely csomagok tartalmazzák az API-t?

A Pro és a Csapatok. Ingyenes vagy Personal csomaggal a kérések API_PLAN_REQUIRED választ adnak.

Olvashatok titkosított fájlokat az API-val?

Nem. A titkosított tartalom név, útvonal, méret és típus nélkül jelenik meg, és a rendszer minden rajta végzett módosítást API_ENCRYPTED_CONTENT hibával elutasít.

Mi történik, ha hálózati hiba miatt megismétlek egy kérést?

Küldd el az Idempotency-Key fejlécet a POST és PATCH kéréseidben. 24 órán át ugyanannak a kérésnek a megismétlése az első választ adja vissza, és semmit sem hoz létre kétszer.

Változhat az API előzetes értesítés nélkül?

Nem. Egy visszafelé nem kompatibilis változás /v2-ként érkezik, a /v1 pedig legalább 12 hónapig megmarad, a Deprecation és a Sunset fejlécekkel.

Források

A lépéseket ezekkel az oldalakkal ellenőriztük.