Přejít na obsah
Sursa Developers

POST/v1/uploads

Zahájit vícedílné nahrávání

create_upload

Otevře relaci nahrávání pro velký soubor (až do limitu instalace pro vícedílné nahrávání, ve výchozím nastavení 5 GB): název, typ obsahu, velikost a purpose, který říká, co nahrávání použije: card_file (POST /v1/cards), archive (POST /v1/cards/archive) nebo import_attachment (příloha dokumentu vlastního zdroje). Odpověď obsahuje id (upl_ a za ním 32 šestnáctkových znaků), velikost části part_size a počet částí part_count. Každá část kromě poslední má přesně part_size bajtů (od 5 do 100 MiB) a poslední část je zbytek. Nedokončené nahrávání platí 24 hodin (expires_at).

Přípona názvu souboru mimo formáty daného účelu vrací 415 uploads.unsupported_format (příloha importu přijímá jakoukoli příponu). Soubor větší než limit instalace nebo než celkové úložiště organizace podle jejího tarifu vrací 413 uploads.too_large. Nedostatek zbývajícího úložiště, včetně nedokončených nahrávání organizace, vrací 402 limits.storage.

Části procházejí přes Sursu (PUT /v1/uploads/{upload_id}/parts/{n}) a v úložišti souborů se šifrují klíčem organizace; přímé odkazy do úložiště neexistují. Nahrávání vidí a může použít jen klíč API nebo uživatel, který ho vytvořil. Přidáno ve verzi 1.62.0.

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry hlavičky

  • Idempotency-Keystring

    Klíč pro bezpečné opakování zápisu: 1 až 255 tisknutelných znaků ASCII; doporučuje se UUID v4 pro každou logickou operaci. Opakování se stejným klíčem do 24 hodin operaci znovu nespustí: vrátí uloženou odpověď (stav, hlavičky a tělo) s hlavičkou Idempotency-Replayed: true. Stejný klíč s jinou metodou, cestou, Content-Type nebo tělem vrací 409 api.idempotency_mismatch; dokud první požadavek ještě běží, vrací 409 api.idempotency_in_progress s Retry-After: 1. Po odpovědi 5xx nebo 429 se klíč uvolní a opakování operaci spustí znovu. Klíč platí v rámci organizace a volajícího (klíč API, uživatel nebo klíč vlastního zdroje).

    length ≥ 1, length ≤ 255

Tělo požadavku

application/json

Objekt: UploadCreate

  • filenamestringpovinné

    Název souboru s příponou; přípona určuje formát.

    length ≥ 1, length ≤ 255

  • content_typestring

    Deklarovaný typ obsahu (MIME); porovnává se se signaturou souboru.

    length ≤ 255

  • sizeinteger (int64)povinné

    Velikost souboru v bajtech.

    ≥ 1

  • purposeUploadPurposepovinné
  • sha256string

    SHA-256 souboru, pokud je známý předem; complete s ním porovná kontrolní součet.

Odpovědi

201Relace nahrávání je vytvořena.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

  • Idempotency-Replayed

    true znamená, že jde o znovu vrácenou uloženou odpověď pro tento Idempotency-Key: operace se znovu nespustila.

application/json

Objekt: Upload

  • idstringpovinné

    ID nahrávání (upl_ a za ním 32 šestnáctkových znaků).

  • purposeUploadPurposepovinné
  • filenamestringpovinné

    Název souboru (bez složek).

  • content_typestringpovinné

    Deklarovaný typ obsahu; prázdný, pokud nebyl deklarován.

  • sizeinteger (int64)povinné

    Velikost souboru v bajtech.

  • sha256string | nullpovinné

    SHA-256 souboru, deklarovaný při vytvoření nebo při complete; null, pokud zatím není známý.

  • statusUploadStatuspovinné
  • part_sizeinteger (int64)povinné

    Velikost každé části kromě poslední (od 5 do 100 MiB).

  • part_countintegerpovinné

    Počet částí.

    ≥ 1, ≤ 1000

  • parts_receivedintegerpovinné

    Počet přijatých částí.

    ≥ 0

  • partsarray of UploadPartpovinné

    Přijaté části podle čísla (v odpovědi POST /v1/uploads prázdné).

  • reject_reasonstring | nullpovinné

    Důvod odmítnutí (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Výčet se může rozšířit; null, pokud nahrávání odmítnuto nebylo.

  • reject_detailsobject | nullpovinné

    Podrobnosti odmítnutí (přípona, deklarovaný a zjištěný formát, kontrolní součty); null, pokud nahrávání odmítnuto nebylo.

  • created_atstring (date-time)povinné

    Kdy bylo nahrávání vytvořeno.

  • expires_atstring (date-time)povinné

    Lhůta pro dokončení nahrávání a – jakmile je připravené – pro jeho použití.

  • completed_atstring (date-time) | nullpovinné

    Kdy kontrola skončila (ready nebo rejected).

  • consumed_atstring (date-time) | nullpovinné

    Kdy bylo nahrávání použito (kartou, archivem nebo importem).

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

402Organizace dosáhla limitu tarifu (karty, úložiště nebo uživatelé). `error.details` obsahuje `kind`, `limit` a `used`.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

413Tělo požadavku překračuje povolenou velikost.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

415Formát souboru není podporován.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

  • Retry-After

    Počet sekund, které je třeba počkat před opakováním požadavku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Bezpečné opakování

S každým požadavkem POST a PATCH odešlete hlavičku Idempotency-Key (například UUID). Opakování se stejným klíčem do 24 hodin vrátí uloženou odpověď, místo aby se požadavek provedl znovu.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← uploads · Reference API