Nahrávací (upload) API s možností přerušení (beta)

Frustruje vás, když nahrávání 5 GB souboru před koncem spadne a vy musíte začínat od začátku? Proto je zde rozhraní k nahrávání souborů na Ulož.to Disk s možností navazování

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í podpisu a dalších informací potřebných pro samotné nahrávání souborů
  3. registrace konkrétního souboru pro nahrávání po blocích
  4. nahrávání souborů, postupně, po jednotlivých blocích
  5. ověření, že soubor nahrávaný po blocích byl na serveru celý úspěšně sestaven
  6. pokud nebyl, nahrání chybějících bloků
  7. opětovné ověření, že soubor nahrávaný po blocích byl na serveru celý úspěšně sestaven
    • volitelná práce s adresářovou strukturou
  8. potvrzení (commit) o ukončení nahrávaní souboru
Schéma základní komunikace nahrávání souborů s možností přerušení 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 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_signature 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í podpisu upload_signature, identifikátoru nahrávací dávky private_slug a domény s vč. protokolu upload_resumable_base_url, kam se budou samotné soubory posílat. V případě vypršení platnosti nahrávacího odkazu, je možno jej pro danou dávku (batch) 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 podpisu
Oficiální API pro získání URL validace captcha
Oficiální API pro volitelné ověření, zda je captcha_token zvalidován

3. Registrace souboru pro nahrávání (tzv. registration)

Před započetím samotného odesílání dat, je potřeba každý nahrávaný soubor nejprve zaregistrovat. Toto se provádí zasláním základních údajů o souboru na upload API na adrese získané z položky odpovědi upload_resumable_base_url předchozího volání (např. https://upload-resumable.greencdn.io/). Odesílané údaje ve formátu JSON jsou:

  • batch_file_id - povinný unikátní 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ů
  • upload_signature - povinný podpis, získaný v předchozím kroku
  • name - povinný název nahrávaného souboru
  • filesize - povinná velikost nahrávaného souboru v bajtech (bytech B)
  • chunksize - povinná velikost bloku, po kterých budou jednotlivé části souboru posílány na server v bajtech (bytech B), povolené velikosti jsou 4 MB (4194304 bajtů), 32 MB (33554432 bajtů) nebo 128 MB (134217728 bajtů)
  • crc32 - volitelný cyklický redundantní součet (UNSIGNED), číslo pro kontrolu konzistence souboru po přenosu

Účelem tohoto kroku je registrace souboru na serveru (v cloudu).

Detaily API pro registraci souboru

Metoda a URL

POST https://upload-resumable.greencdn.io/v1/chunked-file-upload

Tělo požadavku (JSON)

{
   "batch_file_id": 1,
   "upload_signature": "NGNjZXQzNmEtZDEyNS00NGMxLThlMWMtOWU2YjllN2JmMjNSfDE3ZTAzYzhkZTgwN2IxOWMxOGExMTU5MzBhODM3OAI2fDE2NTY", 
   "name": "Dovolená v Bejrůtu.mov", 
   "filesize": 42198263,
   "chunksize": 4194304,
   "crc32": null
}

Příklad odpovědi (JSON)

{
   'valid_until': '2022-06-23 23:08:39', 
   'upload_url': 'https://upload-resumable.greencdn.io/v1/chunked-file-upload/0c9a0f4e-2966-49ce-a022-d0052eeada29/1/1',
   'return_code': 200
}

kde:
  • valid_until = čas, do kdy je nahrávací odkaz platný
  • upload_url = URL adresa, na kterou se ma poslat první část/blok souboru
  • return_code = HTTP kód odpovědi, 200 znamená vše v pořádku, >= 400 signalizuje problém

Smazání zaregistrovaného souboru

Pro smazání již zaregistrovaného souboru, pokud se nebude v jeho nahrávání již zaručeně pokračovat, je doporučeno (ne však nezbytně nutné) provést i jeho smazání. Stačí zavolat HTTP metodu DELETE na URL z odpovědi výše, položku upload_url, ovšem s odebráním posledního lomítka a části za ním, tedy např. na 'https://upload-resumable.greencdn.io/v1/chunked-file-upload/0c9a0f4e-2966-49ce-a022-d0052eeada29/1, které provede smazání prvního zaregistrovaného souboru, https://upload-resumable.greencdn.io/v1/chunked-file-upload/0c9a0f4e-2966-49ce-a022-d0052eeada29/2 druhého apod.

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

Části (bloky) souboru se nahrávají po jednom, každý samostatným HTTP POST požadavkem na adresu upload_url, získanou v předchozím kroku. V této adrese je ale nutno měnit pořadové číslo za posledním lomítkem následovně:

  • získaná podoba upload_url končí vždy /1 a je určená k nahrávání prvního bloku souboru o velikosti chunksize
  • po jeho nahrání je potřeba /1 změnit na /2 a nahrát druhý blok souboru o velikosti chunksize
  • poté pokračovat s /3, /4 apod. dokud se neodešlou všechny bloky souboru
  • poslední blok souboru nemusí samozřejmě splňovat ohlášenou velikost chunksize, ale očekává se zbytek nahrávaného souboru, podle jeho udané velikosti
  • ačkoliv je možné nahrávat jednotlivé bloky souboru v libovolném pořadí, je doporučeno (pro co nejrychlejší zpracování) postupovat od začátku do konce

Účelem tohoto kroku je samotný transfer souboru po blocích z lokálního zařízení na server (do cloudu). Odesílaná binární data mají mít mimetype/hlavičku Content-Type: application/octet-stream.

Detaily API pro přenos bloků souboru

Metoda a URL

POST upload_url /pořadové číslo bloku souboru

Tělo požadavku (RAW DATA)

...blok souboru o velikosti chunksize...

Příklad odpovědi (JSON)

{
   'message': 'Done',
   'return_code': 201
}

kde:
  • message = textový popis úspěchu nebo neúspěchu odesílací operace
  • return_code = HTTP kód odpovědi, 200 znamená vše v pořádku, >= 400 signalizuje problém

5. Ověření stavu nahrávaného souboru (tzv. status check)

Po prvotní registraci souboru k uploadu, je možné se kdykoliv dotázat serveru na jeho stav. Je to vhodné např. po přerušení nahrávání, ale rozhodně je to nutné po odeslání všech bloků souboru, neboť je třeba vyčkat, dokud není na serveru celý soubor složen (a volitelně zkontrolována i jeho integrita). Jakmile je celý soubor na serveru sestaven, je mu přidělen identifikátor slug, který je potřebný pro dokončení povinných nastavení souboru. Z výsledku status volání jsou k dispozici informace:

  • přehled všech údajů z registrace souboru (název, velikost, po jakých blocích se bude nahrávat, do kdy je nahrávací odkaz platný)
  • status, přičemž je nejdůležitější počkat až na stav hotovo (finished)
  • seznam již úspěšně nahraných bloků souboru (uploaded_chunks), podle jejich pořadových čísel
  • seznam bloků souboru, které je ještě potřeba nahrát (missing_chunks), podle jejich pořadových čísel
  • přidělený identifikátor souboru slug, který je k dispozici až po nahrání všech bloků souboru a dosažení statusu finished

Účelem tohoto kroku je ověření aktuálního stavu souboru v cloudu. Jakmile dosáhne soubor stavu finished, již není možné nahrávat další jeho bloky.

Detaily API pro ověření stavu souboru

Metoda a URL

Request: GET https://upload-resumable.greencdn.io/v1/chunked-file-upload/<private_slug>/<batch_file_id>/status

Příklad odpovědi (JSON) ve stavu processing

{
   'name': 'muj soubor.mov',
   'filesize': 42198263,
   'chunksize': 4194304,
   'chunk_count': 11, 
   'expected_crc32': 1302486280,
   'valid_until': '2022-10-24T22:07:46+02:00', 
   'status': 'processing', 
   'return_code': 200, 
   'uploaded_chunks': [1, 2, 3, 4, 5, 6, 7, 8, 9], 
   'missing_chunks': [10, 11]
}

Příklad odpovědi (JSON) ve stavu finished

{
   'name': 'muj soubor.mov',
   'filesize': 42198263,
   'chunksize': 4194304,
   'chunk_count': 11, 
   'expected_crc32': null,
   'valid_until': '2022-10-24T22:07:46+02:00', 
   'status': 'finished', 
   'return_code': 200, 
   'irpc': {
       'slug': 'MqFQWoesyiMD', 
       'filename': 'muj soubor.mov', 
       'filename_changed': false
   },
   'uploaded_chunks': [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], 
   'missing_chunks': []
}

kde sekce irpc, která je k dispozici až poté, co se soubor dostane ze stavu processing (probíha zpracování) do stavu finished nese informace:
  • slug = textový unikátní identifikátor souboru, potřebný pro další práci s ním
  • filename = název souboru tak, jak jej nakonec uložil server; v některých případech se může od původního názvu totiž lišit
  • filename_changed = boolean hodnota udávající, zda bylo do názvu souboru zasahováno nebo nikoliv

6. 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ě)

7. 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é.

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ů 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.

Prodloužení expirovaného povolení k nahrávání souborů

Může dojít k situaci, kdy je nějaký soubor nahrán pouze částečně a přitom dojde k vypršení platnosti povolení k nahrávání.

Server začne další bloky a volání odmítat. Řešením této situace je prodloužit si dosavadní podpis (viz bod 2.) a s obnoveným podpisem pak zavolat metodu prodlužující platnost rozpracovaného souboru.

Po vypršení povolení je možno jeho platnost obnovit jen několik dalších hodin, poté budou nekompletní soubory zahozeny, a proto je doporučeno nečekat, až se tak stane, ale obnovit (prodloužit) si platnost ještě před jeho úplným vypršením.

Detaily API k prodloužení platnosti

Metoda a URL

Request: POST https://upload-resumable.greencdn.io/v1/chunked-file-upload/<identifikátor souborů z registrace>

Tělo požadavku (JSON)

{
   "upload_signature": "NGNjZXQzNmEtZDEyN...", 
}

Příklad odpovědi (JSON)

{
   'message': 'Done',
   'return_code': 200, 
}

kde:
  • message = textový popis neúspěchu prodlužovací operace
  • return_code = HTTP kód odpovědi, 200 znamená vše v pořádku, >= 400 signalizuje problém

Ukázkový kód

K dispozici jsou také dva referenční scripty v jazyce PYTHON a BASH, 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 všech možných chybových stavů v průběhu nahrávání.

Ukázka v jazyce BASH

Ukázka v jazyce Python3 (vyžaduje nainstalovaný modul requests)

Nahrává soubor nebo seznam souborů ze složky na vstupu a po jejich nahrání nahrávací dávku ukončuje.