- 1.Komu je určen tento návod?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).
- 2.K čemu je API Správce souborů?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
- 3.Jak použít API Správce souborů?API se volá webovou operací (https) s parametrem 'url' ukazujícím do Dokumentového serveru, např.:
https://is.vsci.cz/auth/dok/fmgr_api?url=/do/cevro/
API vrací údaje ve formátu XML s kódováním UTF-8. - 4.Jaké parametry lze použít při volání?Povinný je parametr url ukazující do Dokumentového serveru ISu. Příklady použití:
https://is.vsci.cz/auth/dok/fmgr_api?url=/do/cevro
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.vsci.cz/auth/dok/fmgr_api?url=/auth/do/cevro
https://is.vsci.cz/auth/dok/fmgr_api?url=https://is.vsci.cz/auth/do/cevro
https://is.vsci.cz/auth/dok/fmgr_api?url=https://is.vsci.cz/do/cevrohttps://is.vsci.cz/auth/dok/fmgr_api?url=/do/cevro/;strom=1
- 5.Popis předávaných datUzlem 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.vsci.cz nebo https://is.vsci.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.
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.vsci.cz nebo https://is.vsci.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.
- 6.Omezení výpisu velkých stromů při zadání parametru strom=1Bě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>
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.
<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>
... - 7.Příklady použití API Správce souborů pro automatické stahování datPokud 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
nebowget --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.
Nenašli jste odpověď? Pošlete nám svůj dotaz na fi
muni
cz