Programátorské rozhraní Správce souborů (API)

Tato nápověda je určena typicky správcům webových stránek, kteří chtějí na svoje stránky umístit kopie souborů z Dokumentového serveru ISu, například v Dokumentovém serveru uložených předpisů.

API znamená Aplikační programátorské rozhraní (Application Programming Interface).

API Správce souborů je určeno k předávání metadat (dat popisujících data) složek a souborů, které jsou běžnému člověku poskytovány pomocí Správce souborů. Pomocí API lze tedy získat informace o seznamu souborů ve složce, o struktuře složek, či o souboru.

Vlastní obsah souboru není API poskytován, protože ten lze stáhnout přímo z url souboru, např.:

https://is.muni.cz/clanky/ismu-comics.pdf

API se volá webovou operací (https) s parametrem 'url' ukazujícím do Dokumentového serveru, např.:

https://is.caritas-vos.cz/auth/dok/fmgr_api?url=/do/caritas/

API vrací údaje ve formátu XML s kódováním UTF-8.

Povinný je parametr url ukazující do Dokumentového serveru ISu. Příklady použití:

https://is.caritas-vos.cz/auth/dok/fmgr_api?url=/do/caritas
https://is.caritas-vos.cz/auth/dok/fmgr_api?url=/auth/do/caritas
https://is.caritas-vos.cz/auth/dok/fmgr_api?url=https://is.caritas-vos.cz/auth/do/caritas
https://is.caritas-vos.cz/auth/dok/fmgr_api?url=https://is.caritas-vos.cz/do/caritas

Toto volání předá informace o metadatech obsahu složky nebo souboru, na kterou url ukazuje.

Volitelný je parametr strom=1, který zařídí, že se API pokusí vypsat celý strom složek od zadaného url až k souborům. Pokud hrozí, že výpis bude velký, požadavek se neaplikuje nebo se aplikuje jen částečně. Popsáno je podrobněji níže.

Příklad použití parametru strom:

https://is.caritas-vos.cz/auth/dok/fmgr_api?url=/do/caritas/;strom=1

Uzlem se v terminologii ISu rozumí buď složka nebo soubor. "Pod" každý uzel lze zavěsit libovolný počet dalších uzlů (tzn. že i pod soubor lze zavěsit další soubory).

Uzel se souborem je reprezentován jedním nebo více objekty. Různé objekty jednoho uzlu se souborem reprezentují tentýž obsah v různých fomátech (vložíte-li např. soubor s Wordem, IS automaticky vytvoří další dva objekty, jeden s obsahem převedeným do PDF a druhý s obsahem převedeným do holého textu). Ručně vložený objekt je ten, který má pořadí 0. Objektům souboru nelze měnit obsah. Změna obsahu znamená vytvoření nového objektu s novým identifikátorem objekt_id a zařazení pod původní uzel.

Přístupová práva se aplikují na každý uzel zvlášť. API předá metadata jen těch uzlů, na které má uživatel používající rozhraní právo číst.

Údaje předávané k uzlu:

nazev

Volitelný název uzlu.

nazev_en

Volitelný anglický název uzlu.

popis

Volitelný popis uzlu.

zkratka

Zkratka, ze které se tvoří url. Buď zadaná ručně, nebo automaticky použité číslo uzlu v databázi ISu.

vaha_pro_razeni

Volitelně zadané číslo, které po použije pro řazení poduzlů ve výpisech Správce souborů.

expiruje

Volitelné datum, kdy má být soubor smazán. U některých agend nelze použít, u některých agend povinné.

zmeneno

Datum a čas poslední změny uzlu.

zmenil_uco

Učo osoby, která údaje uzlu naposledy změnila.

zmenil_jmeno

Jméno osoby, která údaje uzlu naposledy změnila.

smi_cist_svet

=1, pokud jsou přístupová práva pro čtení obsahu uzlu nastavena tak, že smí číst celý svět.

smi_cist_auth

=1, pokud jsou přístupová práva pro čtení obsahu uzlu nastavena tak, že smí číst všichni přihlášení v ISu.

uzel_id

Identifikační číslo uzlu v databázi ISu.

rodic_id

Identifikační číslo uzlu rodiče (tj. uzlu nadřazené složky) v databázi ISu.

cesta

Obsahuje cestu ke složce nebo k souboru uzlu. Lze použít pro vytvoření url složky nebo souboru přidáním potřebného prefixu, např. https://is.caritas-vos.cz nebo https://is.caritas-vos.cz/auth.

pocet_objektu

Obsahuje počet objektů uzlu, tj. formátů souborů (obsahuje-li např. Word, PDF a txt, pak je =3).

pocet_poduzlu

Obsahuje počet poduzlů uzlu, tzn. kolik je pod uzel zavěšeno podsložek nebo "podsouborů". Pro stanovení tohoto čísla se ignorují přístupová práva.

url_metadata

URL tohoto API s parametrem zajišťujícím získání metadat tohoto uzlu.

Informace k poduzlům:

poradi_poduzlu

Je orientační číslo použité k očíslování položek výpisu. Není nikde uloženo.

Další údaje k poduzlům mají stejný význam jako údaje popsané u uzlu.

Informace předávané o objektech uzlu, tzn. o jednotlivých formátech souboru:

poradi_objektu

Numerické nebo písmenné pořadí objektu k uzlu uložené v databázi ISu. Objekt s pořadím 0 je formát souboru vložený ručně uživatelem. Vyšší čísla pořadí mají automaticky vytvářené objekty (další formáty).

jmeno_souboru

Jméno souboru.

mime_type

Mime-type obsahu souboru.

kodovani

Kódování obsahu souboru, jde-li o soubor textový (u - utf-8, w - windows-1250, i - iso-8859-2).

velikost

Velikost obsahu souboru v bajtech.

vlozeno

Datum a čas vložení souboru.

vlozil_uco

Učo uživatele, který objekt vložil (automaticky vložený objekt učo vloženo nemá).

vlozil_jmeno

Jméno uživatele, který objekt vložil.

objekt_id

Identifikátor objektu uložený v databázi ISu (obsah přiřazený k identifikátoru je neměnný, změna obsahu znamená vytvoření nového objektu s novým identifikátorem).

cesta

Obsahuje cestu k souboru. Lze použít pro vytvoření url souboru přidáním potřebného prefixu, např. https://is.caritas-vos.cz nebo https://is.caritas-vos.cz/auth.

Formát dat při použití parametru strom=1:

Použijeme-li parametr strom=1, projdou se všechny složky (které má uživatel právo číst) a obsahy složek se zařadí do výpisu. Současně se přidá popis struktury (stromu) složek do elementů strom a složka s tímto významem:

url

Cesta ke složce.

uzel_id

Identifikace uzlu se složkou uložená v databázi ISu.

rodic_id

Identifikace uzlu rodičovské (nadřazené) složky v databázi ISu.

zanoreni

Pomocný údaj popisující úroveň zanoření aktuální složky vzhledem ke složce adresované parametrem url.

polozek_v_podstromu

Orientační údaj použitý pro vyhodnocení velikosti složky. Zahrnuje počet uzlů a souborů ve složce a podsložkách spočítaný bez ohledu na přístupová práva.

obsah_slozky_ignoruji_ctete_metadata

Popis a příklad použití elementu obsah_slozky_ignoruji_ctete_metadata vizte níže.

Během zpracování parametru strom=1 se zkoumá, zda složka, které se má vypsat, je příliš velká nebo zda hrozí, že složka může být velká. Potenciálně velké složky se z výpisu vyřadí.

Pokud je složka vyřazena z výpisu, je v XML vyznačena elementem obsah_slozky_ignoruji_ctete_metadata např. následovně:

<strom>
 <slozka url="/do/mu/Uredni_deska/Predpisy_MU/Masarykova_univerzita/" ... >
  <obsah_slozky_ignoruji_ctete_metadata>
   https://is.muni.cz/auth/dok/fmgr_api?url=/do/mu/Uredni_deska/Predpisy_MU/Masarykova_univerzita/;strom=1
  </obsah_slozky_ignoruji_ctete_metadata>
 </slozka>
 ...

Použijete-li parametr strom=1, musíte kontrolovat, zda se neobjeví element obsah_slozky_ignoruji_ctete_metadata. Pokud ano, použijte k načtení metadat složky v obsahu elementu uvedený odkaz.

Pokud budete používat API Správce souborů pro opakované automatické operace, využijte neosobní účet (Nápověda).

Např. z unixového systému můžete pro stažení dat z ISu použít:

curl -u '999999:xxxxxxxx' 'https://is.muni.cz/auth/dok/fmgr_api?url=/do/fi/uredni_deska/predpisy;strom=1' > vystup.xml

nebo

wget --auth-no-challenge --user 999999 --password 'xxxxxxxx' 'https://is.muni.cz/auth/dok/fmgr_api?url=/do/fi/uredni_deska/predpisy'

kde 999999 je učo neosobního účtu a xxxxxxxx je heslo neosobního účtu.