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

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

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ý

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.

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

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

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

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

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

{
   '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
}

Čá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.

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

...blok souboru o velikosti chunksize...

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

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.

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

{
   '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]
}

{
   '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': []
}

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

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ů

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

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.

Oficiální API pro vytváření složek

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.

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.