Ugrás a tartalomra
Sursa Developers

POST/v1/uploads

Többrészes feltöltés indítása

create_upload

Feltöltési munkamenetet nyit egy nagy fájlhoz (a telepítés többrészes feltöltésre vonatkozó korlátjáig, amely alapértelmezés szerint 5 GB): a név, a tartalomtípus, a méret és a purpose rendeltetés, amely megmondja, mi fogja felhasználni a feltöltést: card_file (POST /v1/cards), archive (POST /v1/cards/archive) vagy import_attachment (egy egyéni forrás dokumentumának melléklete). A válasz tartalmazza az id azonosítót (upl_, majd 32 hexadecimális karakter), a part_size részméretet és a part_count részszámot. Az utolsó kivételével minden rész pontosan part_size bájt (5 és 100 MiB között), az utolsó rész a maradék. A befejezetlen feltöltés 24 óráig él (expires_at).

Ha a fájlnév kiterjesztése kívül esik a rendeltetés formátumain, a válasz 415 uploads.unsupported_format (az importálási melléklet bármilyen kiterjesztést elfogad). Ha a fájl nagyobb a telepítés korlátjánál vagy a szervezet csomagja szerinti teljes tárhelynél, a válasz 413 uploads.too_large. Ha – a szervezet befejezetlen feltöltéseit is beszámítva – nem marad elég tárhely, a válasz 402 limits.storage.

A részek a Sursán keresztül érkeznek (PUT /v1/uploads/{upload_id}/parts/{n}), és a fájltárban a szervezet kulcsával titkosítva tárolódnak; a tárhelyre mutató közvetlen hivatkozások nincsenek. A feltöltést csak az azt létrehozó API-kulcs vagy felhasználó láthatja és használhatja. Az 1.62.0 verzióban jelent meg.

Hitelesítés

Küldj egy API-kulcsot az Authorization fejlécben: Authorization: Bearer <kulcs>.

Fejlécparaméterek

  • Idempotency-Keystring

    Kulcs egy írási kérés biztonságos megismétléséhez: 1–255 nyomtatható ASCII-karakter; logikai műveletenként egy UUID v4 ajánlott. Ha 24 órán belül ugyanazzal a kulccsal ismétled meg a kérést, a művelet nem fut le újra: a mentett választ kapod vissza (állapot, fejlécek és törzs) az Idempotency-Replayed: true fejléccel. Ugyanaz a kulcs más metódussal, útvonallal, Content-Type értékkel vagy törzzsel 409 api.idempotency_mismatch választ ad; amíg az első kérés még fut, a válasz 409 api.idempotency_in_progress, Retry-After: 1 fejléccel. 5xx vagy 429 válasz után a kulcs felszabadul, és a megismételt kérés újra lefuttatja a műveletet. A kulcs a szervezethez és a hívóhoz (API-kulcs, felhasználó vagy egyéni forrás forráskulcsa) kötődik.

    length ≥ 1, length ≤ 255

Kéréstörzs

application/json

Objektum: UploadCreate

  • filenamestringkötelező

    A fájl neve a kiterjesztéssel együtt; a kiterjesztés határozza meg a formátumot.

    length ≥ 1, length ≤ 255

  • content_typestring

    A megadott tartalomtípus (MIME); a rendszer összeveti a fájl szignatúrájával.

    length ≤ 255

  • sizeinteger (int64)kötelező

    A fájl mérete bájtban.

    ≥ 1

  • purposeUploadPurposekötelező
  • sha256string

    A fájl SHA-256 kivonata, ha előre ismert; a complete ehhez hasonlítja a fájl ellenőrzőösszegét.

Válaszok

201A feltöltési munkamenet létrejött.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

  • Idempotency-Replayed

    A true azt jelenti, hogy a válasz az ehhez az Idempotency-Key kulcshoz mentett válasz megismétlése: a művelet nem futott le újra.

application/json

Objektum: Upload

  • idstringkötelező

    A feltöltés azonosítója (upl_, majd 32 hexadecimális karakter).

  • purposeUploadPurposekötelező
  • filenamestringkötelező

    A fájl neve (mappák nélkül).

  • content_typestringkötelező

    A megadott tartalomtípus; üres, ha nem adták meg.

  • sizeinteger (int64)kötelező

    A fájl mérete bájtban.

  • sha256string | nullkötelező

    A fájl SHA-256 kivonata, amelyet a létrehozáskor vagy a complete hívásakor adtak meg; null, ha még nem ismert.

  • statusUploadStatuskötelező
  • part_sizeinteger (int64)kötelező

    Az egyes részek mérete az utolsó kivételével (5 és 100 MiB között).

  • part_countintegerkötelező

    A részek száma.

    ≥ 1, ≤ 1000

  • parts_receivedintegerkötelező

    A beérkezett részek száma.

    ≥ 0

  • partsarray of UploadPartkötelező

    A beérkezett részek sorszám szerint (a POST /v1/uploads válaszában üres).

  • reject_reasonstring | nullkötelező

    Az elutasítás oka (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. A felsorolás bővülhet; null, ha a feltöltés nincs elutasítva.

  • reject_detailsobject | nullkötelező

    Az elutasítás részletei (a kiterjesztés, a megadott és a felismert formátum, az ellenőrzőösszegek); null, ha a feltöltés nincs elutasítva.

  • created_atstring (date-time)kötelező

    A feltöltés létrehozásának időpontja.

  • expires_atstring (date-time)kötelező

    Határidő a feltöltés befejezésére, és ha már kész, a felhasználására is.

  • completed_atstring (date-time) | nullkötelező

    Az ellenőrzés befejezésének időpontja (ready vagy rejected).

  • consumed_atstring (date-time) | nullkötelező

    A feltöltés felhasználásának időpontja (kártya, archívum vagy importálás által).

401Nem érkeztek hitelesítő adatok (sem munkamenet-süti, sem API-kulcs), vagy a kulcs nem található.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

402A szervezet elérte valamelyik csomagkorlátját (kártyák, tárhely vagy felhasználók). Az `error.details` a `kind`, a `limit` és a `used` mezőt tartalmazza.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

403A művelet nem engedélyezett: a szerepkör nem elegendő, nincs hozzáférés a gyűjteményhez vagy a kártyához, a kérés „View as” módban fut, vagy a szervezetet felfüggesztették vagy törölték (a `detail` egy objektum, `code: org_suspended | org_deleted` mezővel).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

413A kéréstörzs meghaladja a megengedett méretet.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

415A fájlformátum nem támogatott.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

422Érvényesítési hiba: a törzs vagy a paraméterek nem felelnek meg a sémának (a `detail` az érvényesítési hibák listája), vagy egy paraméter értéke kívül esik a megengedett tartományon (a `detail` egy üzenet).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

429Túl sok kérés (`api.rate_limited`), elfogyott a szervezet percre, napra vagy hónapra szóló kvótája (`api.quota_exceeded`; az `error.details` a `quota`, a `limit` és a `reset_at` mezőt tartalmazza), a szervezet elérte a korlátját, vagy a válaszszolgáltatás foglalt (`answers.engine_busy`). Várj a `Retry-After` fejlécben megadott ideig.

Válaszfejlécek

  • Retry-After

    Ennyi másodpercet várj, mielőtt újrapróbálod a kérést.

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

Hibakódok

Azok a kódok, amelyeket ez a végpont hiba esetén az error.code mezőben visszaadhat, a minden kérésre érvényes általános kódokon kívül.

Biztonságos újrapróbálkozás

Minden POST és PATCH kéréssel küldj Idempotency-Key fejlécet (például egy UUID-t). Ha 24 órán belül ugyanazzal a kulccsal megismétled a kérést, a mentett választ kapod vissza, és a kérés nem fut le újra.

Gyakorisági korlátok

A válaszokban ott van a RateLimit és a RateLimit-Policy fejléc, valamint a korábbi X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejléc. A 429-es válasz Retry-After fejléce másodpercben adja meg a várakozást: várj, majd próbáld újra.

← uploads · API-referencia