Nahrávací (upload) API (gama, dříve beta)

Rozhraní k nahrávání souborů na Ulož.to Disk

Pro přenos dat se používá výhradně zabezpečený protokol HTTPS. Jako kódování znakové sady se používá UTF-8. Jako datový protokol se používá JSON.
Obecně platí, že návratové HTTP kódy volání v rozsahu 200-299 signalizují, že požadavek byl vyřízen v pořádku, hodnoty v rozsahu 400-499 znamenají, že došlo k chybě a je k dispozici vysvětlení povahy chyby v těle odpovědi, hodnoty v rozsahu 500-599 znamenají, že služba nefunguje správně a je doporučeno vyčkat a zkusit volání později.

Základní komunikační flow pro nahrávání souborů

  1. přihlášení se ke svému účtu a získání autorizačního tokenu
  2. získání URL a dalších informací potřebných pro samotné nahrávání souborů
  3. nahrávání souborů, po jednom
    • volitelná práce s adresářovou strukturou a viditelností
  4. potvrzení (commit) ukončení nahrávaní souborů
Schéma základní komunikace nahrávání souborů Schéma základní

Validace pomocí captcha

V ojedinělých případech, jako je nahrávaní souborů z území mimo ČR a SR, může být vydání platného odkazu pro nahrávání souborů podmíněno úspěšnou uživatelskou validací pomocí captcha mechanismu (konkrétně Google reCaptcha). V takových případech je komunikační schéma následující (přihlašovaní k účtu a samotné nahrávání souborů je pro zjednodušení v tomto případě vypuštěno):

  1. získání URL pro nahrávání souborů je neúspěšné a je požadována validace captcha tokenu
  2. získání URL HTML stránky pro validaci captcha tokenu
  3. validace captcha tokenu pomocí webového prohlížeče, HTML a JavaScriptu (provádí uživatel)
    • volitelné ověření, zda je token opravdu správně zvalidován
  4. opakovaný pokus o získání URL pro nahrávání souborů se zvalidovaným captcha tokenen, bude úspěšný
Schéma komunikace pro provedení captcha validace Schéma validační

Jak získat X-Auth-Token neboli API klíč

Aktuální X-Auth-Token (API klíč), určený pouze pro potřeby testování, je: ;HG%7jW6@6/8vx">R;f(

S tímto tokenem si lze vše vyzkoušet a odladit. Klíč se může kdykoliv změnit a přestat platit.
Jakmile je aplikace připravena pro řádné používání, je potřeba si pro ni a konkrétní uživatelský účet vyžádat přidělení dedikovaného API klíče kontaktováním uživatelské podpory.

1. Autorizace k uživatelskému účtu (tzv. authentication and authorization)

První krok, bez kterého nelze nahrávání souborů započít. HTTP metoda PUT. Účelem je získání autorizovaného AI uživatelského tokenu token_id. Pro volitelnou organizaci souborů do složek se bude později hodit také identifikátor hlavní složky uživatele root_folder_slug. Pro přihlašování použijte namísto hesla aplikační login token, který získáte v Nastavení.

Oficiální API pro autorizaci uživatele

2. Získání základních informací pro nahrávání (tzv. upload link and batch slug)

Pro započetí nahrávání je potřeba několika základních informací + znalost jak tyto informace dále používat. Provádí se skrze HTTP metodu POST. Účelem je získání upload_url, tedy adresy pro samotné nahrání souboru a identifikátoru nahrávací dávky private_slug. V případě vypršení platnosti nahrávacího odkazu, je možno jej pro danou dávku opakovaně obnovit posláním v těle požadavku.
Při nahrávání především ze zemí mimo ČR a SR, může API rovněž vyžadovat ověření captcha_tokenu nahrávajícím uživatelem. V takovém případě je namísto běžné odpovědi navrácen captcha_token, který je potřeba zvalidovat.

Oficiální API pro získání nahrávacího odkazu
Oficiální API pro získání URL validace captcha
Oficiální API pro volitelné ověření, zda je captcha_token zvalidován

3. Nahrání samotného souboru (tzv. upload)

Soubory se nahrávají zásadně po jednom, každý samostatným HTTP POST požadavkem na adresu upload_url, získanou v předchozím kroku. Do této adresy je nutno doplnit ve formátu GET parametrů tyto údaje:

  • batch_file_id - unikatní celočíselný kladný, nenulový identifikátor nahrávaného souboru. Pro první soubor v rámci nahrávání to může být hodnota 1, pro druhý 2, pro třetí 3 atd., ačkoliv pořadí nehraje roli, důležitá je unikátnost v rámci nahrávané dávky souborů
  • is_porn - vždy booleovská hodnota false.
  • příklady:
    • pro v pořadí první soubor nahrávaný na Ulož.to Disk se k hodnotě upload_url doplní na konec &batch_file_id=1&is_porn=false

Účelem tohoto kroku je samotný transfer souboru z lokálního zařízení na server (do cloudu).

Detaily API pro přenos souborů

Hlavičky požadavku

URL
POST upload_url + &batch_file_id=1&is_porn=false

Povinné hlavičky
ContentType: multipart/form-data
 

Tělo požadavku (multipart-formdata)

Pro HTTP POST metodu zakódovaný soubor k nahrání.

Příklad odpovědi (JSON)

{
   "size": 1260559,
   "contentType": "document",
   "md5": "83e6597fbaf8faa6dc2fa1c31b640dee",
   "message": "Done",
   "return_code": 200,
   "slug": "5QtEPnp2z1l"
}

kde:
  • size = velikost odeslaného souboru v bytech (bajtech)
  • contentType = výsledek detekce typu nahrávaného obsahu
  • md5 = MD5 hash spočítaný na straně serveru po přenosu celého souboru
  • message = textová zpráva o tom, jak nahrání souboru dopadlo, "Done" znamená vše v pořádku, cokoliv jiného popisuje chybu
  • return_code = HTTP kód výsledku nahrávání, 200-299 signalizuje "Vše v pořádku", kódy 400-599 signalizují, že došlo k chybě

4. Nastavení vlastností souboru

Po dokončení nahrávání je nutné nastavit souborům složku tzv. parent folder pomocí metody PATCH.

  • složka (folder_slug) - slug složky (jak vytvořit složku novou nebo vybrat ze seznamu existujících je popsáno níže)
  • při použití API pro změnu více (dosud necommitovaných) souborů najednou (tzv. bulk režim), je potřeba položku upload_tokens naplnit seznamem X-Upload-Tokenů jednotlivých souborů a položku slugs seznamem získaných identifikátorů po nahrání; seznamy upload_tokens a slugs musí tvořit odpovídající páry tokenů a slugů již nahraných souborů!
  • metodu PATCH je možno jednodušeji použít i později, pro již commitované soubory, bez potřeby používání X-Upload-Tokenů

Oficiální API pro změnu vlastností nahrávaných souborů (po jednom)
Oficiální API pro změnu vlastností nahrávaných souborů (hromadně)

5. Potvrzení o ukončení nahrávání souborů (tzv. commit)

Pokud je úspěšně nahrán jeden nebo více souborů, je potřeba nahrávání ukončit a potvrdit voláním akce commit HTTP metodou PUT. Bez zavolání commitu nejsou soubory na službě Ulož.to Disk viditelné ani pro veřejnost, ani pro majitele uživatelského účtu.

Oficiální API pro commit nahrávaných souborů

Seznam složek na uživatelském účtu (tzv. folder list)

Pro uživatele s větším množstvím souborů je není vhodné nahrávat všechny soubory do hlavní kořenové (tzv. root) složky (její identifikátor je root_folder_slug), ale pracovat s hierarchií složek. Limit na jakoukoliv složku je 10.000 souborů. Každá složka má svůj slug identifikátor, k jehož získání slouží právě toto rozhraní.

Účelem je získání seznamu složek a jejich slug identifikátorů pro použití v metodě nastavování vlastností souborů.

Oficiální API pro získání seznamu složek

Vytvoření nové složky (tzv. create folder)

Základní struktura složek nemusí být vždy dostatečná, a proto je k dispozici i možnost založit novou uživatelskou složku. Metoda vyžaduje slug identifikátor nadřazené složky, kde se má nová složka vytvořit.

Ukázkový kód

K dispozici jsou také tři referenční scripty v jazyce BASH a PYTHON, které nahrávání na Ulož.to Disk pomocí API demonstrují a které jsou po doplnění potřebných parametrů plně funkční. Jejich účelem je usnadnit pochopení API i případnou implementaci uživatelské aplikace napojené na Ulož.to Disk API.
Implementace je pouze příkladová a neošetřuje výskyt možných chybových stavů v průběhu nahrávání.

Ukázka v jazyce BASH
Ukázka v jazyce Python (vyžaduje nainstalovaný modul requests)
Nahrává soubor nebo seznam souborů ze složky ze vstupu a po jejich nahrání nahrávací dávku ukončuje.