Usermap API

Usermap API (pracovní název) je agregátor údajů o identitách lidí na ČVUT, který vyvíjíme na FIT. Poskytuje základní informace o osobě jako je jméno, uživatelské jméno, emailové adresy, telefony, … a tzv. byznys role (z IDM). Dále obsahuje informace o organizačních jednotkách ČVUT a místnostech (vč. adresy).

Primární datové zdroje

Primárním zdrojem dat je Usermap (SSU), konkr. Usermap LDAP, jeho relační přívěšek EXT_UMAP a KOS (pro předmětové role). Více informací o datové doméně Usermap najdete na této stránce. Dále se synchronizuje s fakultním IDM FIT, odkud se přebírají další fakultní role osob a identity externistů.

RESTful API

Dokumentaci prvotní verze RESTového API zatím najdete tady (generované z RAML).

API podporuje parametrické dotazy pomocí RSQL. Ke standardním operátorům přidává ještě operátor =all=; hodnota nebo kolekce hodnot musí obsahovat všechny uvedené argumenty.

API je zabezpečeno protokolem OAuth 2.0 a využívá fakultní autorizační server.

Poskytované role

Usermap API zprostředkovává všechny tzv. celoškolské business role a naše fakultně specifické business i technické role z fakultního IDM. Dále poskytuje tzv. předmětové role (vztah osoby k vyučovanému předmětu), které generuje z KOSu.

Předmětové role

Předmětové role mají obdobnou strukturu jako business role, ale místo organizační jednotky se váží na konkrétní předmět (podle jeho kódu). Kód předmětu je v rámci ČVUT unikátní.

* Role editor (v KOSu se jmenuje AUTORNAV) zmocňuje daného vyučujícího editovat informace o předmětu.

Některé předměty jsou ve vztahu rozvrhovaný (nadřízený) a zapisovaný (podřízený). Týká se to typicky tělocviků a jazyků. Rozvrhovaný předmět je jakýsi metapředmět, který sdružuje různé „instance“ téhož předmětu, typicky na různých fakultách. Studenti se zapisují na zapisované (podřízené) předměty a zkoušky, ale vyučující je všechny vidí v rámci rozvrhovaného (nadřízeného) předmětu. V těchto případech se generují role pouze pro rozvrhované předměty, ale v atributu role courses jsou uvedeny kódy všech předmětů, kterých se týká, tedy rozvrhovaného i příp. zapisovaných.

Předmětová role pro učitele vzniká v momentně, kdy mají rozvrháři připravený rozvrh pro příští semestr; typicky 1–2 týdny před závaznými zápisy předmětů (viz harmonogram semestru). Zaniká pak s koncem semestru (tj. koncem zkouškového období daného semestru).

Kdy má vznikat studentská role ještě není dořešeno, momentálně vzniká se začátkem semestru a zaniká s jeho koncem.

Příklady

Dotazy přes curl

Uvedené příklady využívají CLI utilitu curl, lze však použít i libovolný jiný HTTP klient, vč. webového prohlížeče.

1. Vypsat uživatele jirutjak (ve formátu JSON):

   curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
   'https://kosapi.fit.cvut.cz/usermap/v1/people/jirutjak'

2. Najít uživatele s uživatelským jménem jirutjak, spaceji3 a szolatib:

   curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
   'https://kosapi.fit.cvut.cz/usermap/v1/people?query=username=in=(jirutjak,spaceji3,szolatib)'

3. Najít uživatele, kteří mají role B-18000-ZAMESTNANEC a B-00000-STUDENT, a zároveň nemají roli B-18000-STUDENT:

   curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
   'https://kosapi.fit.cvut.cz/usermap/v1/people?query=roles=all=(B-81000-ZAMESTNANEC,B-00000-STUDENT);roles=out=(B-18000-STUDENT)'

4. Najít uživatele, kteří mají role B-18000-ZAMESTNANEC a B-00000-STUDENT, nebo B-13000-ZAMESTNANEC a B-00000-STUDENT:

   curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
   'https://kosapi.fit.cvut.cz/usermap/v1/people?query=roles=all=(B-81000-ZAMESTNANEC,B-00000-STUDENT),roles=all=(B-82000-ZAMESTNANEC,B-00000-STUDENT)'

5. Najít uživatele, kteří mají email kevin.flynn@fit.cvut.cz:

   curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
   'https://kosapi.fit.cvut.cz/usermap/v1/people?query=emails==kevin.flynn@fit.cvut.cz'

6. Najít uživatele, jejichž jméno/příjmení začíná na Pav Kor a pracují na FIT:

   curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
   -G 'https://kosapi.fit.cvut.cz/usermap/v1/people' --data-urlencode 'query=name=="Pav Kor";roles==B-18000-ZAMESTNANEC'
   curl špatně enkóduje některé znaky v URI, tady uvozovky a mezera, proto je nutné předat query string přes --data-urlencode.

7. Vypsat detaily role B-18000-ZAMESTNANEC:

   curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
   https://kosapi.fit.cvut.cz/usermap/v1/roles/B-18000-ZAMESTNANEC

Pozor na to, že výstup je stránkovaný; výchozí hodnota je 10 záznamů. Pro zvýšení limitu slouží URI parametr limit, pro určení prvního záznamu parametr offset. Například pro získání 100 záznamů, počínaje padesátým:

Parsování JSON z příkazové řádky

Pro pohodlné parsování JSONu v shellu lze použít například nástroj jq. Výstup z curlu je možné do něj poslat přímo přes pipu.

1. Vypsání celého jména jednoho uživatele:

   jq -r '. | .fullName'

2. Vypsání celého jména více uživatelů v kolekci:

   jq -r '.[] | .fullName'

3. Vypsání všech rolí jednoho uživatele jako seznam oddělený novou řádkou:

   jq -r '. | .roles | join("\n")'

4. Vypsání uživatelského jména, celého jména a preferovaného emailu kolekce uživatelů jako CSV:

   jq -r '.[] | [.username, .fullName, .preferredEmail ] | @csv'