Vadovai

Pradėkite naudotis Nubbo API

Nuo nulio iki pirmosios užklausos per kelias minutes. Sukurkite raktą ir valdykite savo saugyklą iš savo kodo.

Nubbo API yra REST API, skirta dirbti su jūsų bucket iš jūsų pačių kodo: failai, aplankai, nuorodos, failų užklausos, galerijos, žymos, projektai ir automatizavimai. Šiame vadove sukursite raktą ir išsiųsite pirmąsias užklausas su curl.

Ką gaunate

  • Tvarkykite savo Nubbo erdvę iš savo programų su raktais, kurie mato tik tai, ką pasirenkate.
  • Įkelkite ir atsisiųskite failus tiesiai tarp savo kodo ir saugyklos teikėjo.
  • Reaguokite į naujus failus, įkėlimus į failų užklausas ir veiklą naudodami trigerius.

Prieš pradedant

Jums reikia Nubbo paskyros su Pro arba Komandos planu ir terminalo su curl. Komandoje API raktus kuria savininkas arba administratorius.

1 žingsnis: sukurkite raktą

  1. Nubbo atidarykite Nustatymai › API (arba Komanda › API komandoje) ir spauskite Sukurti API raktą.

  2. Suteikite jam pavadinimą ir pasirinkite:

    • Prieiga: Tik skaitymas arba Skaitymas ir rašymas.
    • Aprėptis: Visa erdvė arba Pasirinkti bucket’ai ir projektai. Raktas mato tik tai, ką pasirinksite čia.
    • Galiojimas: 30 dienų, 90 dienų, 1 metai arba Be galiojimo pabaigos. Nubbo jus įspėja prieš 7 dienas.

    Spauskite Sukurti raktą. Nubbo paprašo slaptažodžio, kad patvirtintų, jog tai jūs. Jei naudojate dviejų veiksmų patvirtinimą, Nubbo paprašo ir kodo.

    Langas Sukurti API raktą su prieiga, aprėptimi ir galiojimu Langas Sukurti API raktą su prieiga, aprėptimi ir galiojimu
  3. Nukopijuokite raktą ir spauskite Jau išsaugojau. Jis prasideda nbk_, ir tai vienintelis kartas, kai jį matysite visą. Laikykite jį serveryje arba įrankyje, kuris jį naudos, niekada ne tinklalapyje.

    Langas Jūsų API raktas su raktu, paruoštu kopijuoti Langas Jūsų API raktas su raktu, paruoštu kopijuoti

2 žingsnis: pirmoji užklausa

Siųskite raktą kiekvienos užklausos antraštėje Authorization. Pradėkite nuo GET /v1/me, kuri nenaudoja užklausų kvotos:

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

Atsakyme rasite savo erdvę, planą, mėnesio kvotą ir raktą su jo prieiga bei aprėptimi. Štai ištrauka:

{
  "workspace": { "id": "…", "name": "Šiaurės studija", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Mano pirmasis raktas",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Tada gaukite savo bucket ir vieno aplanko failų sąrašą:

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

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

Sąrašai grąžina data ir nextCursor. Kitam puslapiui siųskite tą reikšmę lauke cursor. Kai nextCursor yra null, daugiau nieko nėra.

Terminalas su užklausa GET /v1/me ir jos atsakymu Terminalas su užklausa GET /v1/me ir jos atsakymu

3 žingsnis: dokumentacija

Skiltyje Nustatymai › API spauskite Peržiūrėti dokumentaciją arba atidarykite api.nubbo.app/v1/docs. Ten rasite kiekvieną išteklių su laukais ir pavyzdžiais. OpenAPI dokumentas yra api.nubbo.app/v1/openapi.json.

Nubbo API dokumentacija su curl pavyzdžiu Nubbo API dokumentacija su curl pavyzdžiu

Įkėlimai ir atsisiuntimai

Failai nepereina per Nubbo. Norėdami įkelti failą, paprašykite įkėlimo su POST /v1/buckets/{bucketId}/uploads, nusiųskite failą į grąžintą iš anksto pasirašytą adresą ir užbaikite su POST /v1/uploads/{uploadId}/complete. Norėdami atsisiųsti, paprašykite nuorodos su POST /v1/files/{fileId}/download-link ir atsisiųskite failą iš savo teikėjo.

Limitai

ProKomandos
Užklausos per minutę vienam raktui60120
Užklausos per mėnesį50 000100 000 + 10 000 už vietą
Trigerių įvykiai per mėnesį20 00050 000 + 5 000 už vietą

Kvota priklauso erdvei ir atsinaujina kiekvieną atsiskaitymo laikotarpį. GET /v1/me, trigerių užklausos ir atsakymai 401, 429 bei 5xx neskaičiuojami kaip užklausos. Kiekvienas trigerio pristatytas įvykis skaičiuojamas kaip įvykis. Kiekviename atsakyme yra antraštės X-RateLimit-Remaining ir X-Nubbo-Quota-Requests-Remaining, o skiltyje Nustatymai › API matote laikotarpio naudojimą.

Laikotarpio API naudojimas Nubbo nustatymuose Laikotarpio API naudojimas Nubbo nustatymuose

Jei kas nors nepavyksta

  • API_KEY_INVALID, API_KEY_REVOKED arba API_KEY_EXPIRED: raktas netinkamas, atšauktas arba nebegalioja. Patikrinkite antraštę arba sukurkite kitą raktą.
  • API_PLAN_REQUIRED: rakto erdvė neturi API. Ji yra Pro ir Komandos planuose.
  • API_KEY_READ_ONLY: raktas skirtas tik skaitymui. Sukurkite raktą su Skaitymas ir rašymas.
  • API_RATE_LIMITED: per daug užklausų su šiuo raktu. Palaukite Retry-After nurodytas sekundes ir bandykite dar kartą.
  • API_QUOTA_EXCEEDED: erdvė išnaudojo mėnesio limitą. details.resetsAt nurodo, kada jis atsinaujins.

Kiekviena klaida turi requestId. Nurodykite jį, jei mums rašote.

Daugiau apie Nubbo API. Norėdami ja naudotis nerašydami kodo, sekite Zapier, n8n arba Make vadovą. Norėdami ja naudotis iš savo AI asistento, pažiūrėkite, kaip prijungti Nubbo prie Claude, ChatGPT arba Cursor.

Dažnai užduodami klausimai

Kurie planai apima API?

Pro ir Komandos. Su Nemokamas arba Personal planu užklausos grąžina API_PLAN_REQUIRED.

Ar galiu skaityti užšifruotus failus per API?

Ne. Užšifruotas turinys rodomas be pavadinimo, kelio, dydžio ir tipo, o bet koks jo keitimas atmetamas su API_ENCRYPTED_CONTENT.

Kas nutinka, jei pakartoju užklausą dėl tinklo klaidos?

Siųskite antraštę Idempotency-Key savo POST ir PATCH užklausose. 24 valandas ta pati pakartota užklausa grąžina pirmąjį atsakymą ir nieko nesukuria du kartus.

Ar API pasikeis be įspėjimo?

Ne. Nesuderinamas pakeitimas ateina kaip /v2, o /v1 išlieka bent 12 mėnesių su antraštėmis Deprecation ir Sunset.

Šaltiniai

Žingsniai patikrinti pagal šiuos puslapius.