Návody FIT
Jdi na navigaci

USERapi

USERapi 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 role. Dále obsahuje informace o organizačních jednotkách ČVUT a místnostech (vč. adresy).

Primární datové zdroje

Datovými zdroji jsou Usermap DB a KOS DB provozované VIC ČVUT.

RESTful API

Dokumentaci prvotní verze RESTového API zatím najdete tady.

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

USERapi zprostředkovává všechny celoškolské role (zdroj Usermap) a 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 celoškolské 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í.

P-MI-W20-UCITEL-PREDNASEJICI
| \____/ \_________________/
|   |            |
|   |            +---------- název role
|   +----------------------- kód předmětu
+--------------------------- typ role předmětová
Název roleČeský popisAnglický popis
STUDENTstudent předmětustudent of the course
UCITELučitel předmětuteacher of the course
UCITEL-CVICICIcvičící předmětuinstructor of the course
UCITEL-CVICICI-LABORATORElaboratorní cvičící předmětulaboratory instructor of the course
UCITEL-EDITOR[1]editor předmětueditor of the course
UCITEL-GARANTgarant předmětuguarantor of the course
UCITEL-PREDNASEJICIpřednášející předmětulecturer of the course
UCITEL-ZKOUSEJICIzkoušející předmětuexaminer of the course

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'
    Důležité:

    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:

https://kosapi.fit.cvut.cz/usermap/v1/people?roles==B-18000-STUDENT&offset=50&limit=100

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'
  1. Role editor (v KOSu se jmenuje AUTORNAV) zmocňuje daného vyučujícího editovat informace o předmětu. ↩