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

  • 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.ucp.cz/auth/dok/fmgr_api?url=/do/vsh/
    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.ucp.cz/auth/dok/fmgr_api?url=/do/vsh
    https://is.ucp.cz/auth/dok/fmgr_api?url=/auth/do/vsh
    https://is.ucp.cz/auth/dok/fmgr_api?url=https://is.ucp.cz/auth/do/vsh
    https://is.ucp.cz/auth/dok/fmgr_api?url=https://is.ucp.cz/do/vsh
    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.ucp.cz/auth/dok/fmgr_api?url=/do/vsh/;strom=1

  • 5.Popis předávaných dat
    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.ucp.cz nebo https://is.ucp.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.ucp.cz nebo https://is.ucp.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=1
    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.

  • 7.Příklady použití API Správce souborů pro automatické stahování dat
    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.


Nenašli jste odpověď? Pošlete nám svůj dotaz na ucpis(zavináč/atsign)fi(tečka/dot)muni(tečka/dot)cz.