3. diel - Path a query parametre vo FastAPI

V minulej lekcii, Zoznámenie s FastAPI frameworkom pre Python , sme si vytvorili svoju prvú webovú aplikáciu vo frameworku FastAPI pre Python. Založili sme projekt a vypísali hlášku "Hello World".

V dnešnom tutoriáli webových aplikácií s frameworkom FastAPI sa pozrieme na rozdiel medzi path a query parametrami. Vysvetlíme si význam a výhody typových anotácií a zameriame sa aj na nepovinné parametre funkcií.

V priebehu kurzu postupne vytvoríme filmovú databázu. Príklady (premenné, názvy tried, parametre a podobne) teda budeme pomenovávať v tomto duchu už teraz, aj keď samotný projekt začneme tvoriť až v neskorších lekciách.

Parametre path vs query

Parameter path ("parameter cesty") je parameter požiadavky vložený do URL adresy, ktorý ukazuje na špecifickú lokalitu zdroja. V URL je oddelený lomítkom od domény, napríklad v URL https://example.com/movies/1/ je číslovka jedna path parametrom (konkrétne sa jedná o id filmu, ako uvidíme neskôr). Tento parameter je povinnou súčasťou požiadavky na server a musí teda vždy niesť nejakú hodnotu, ktorú je možné zmeniť, pretože je dynamická. Oproti tomu je časť /movies/ v URL vyššie považovaná za súčasť cesty, ktorá je pevne daná, nemenná.

Zatiaľ čo path identifikuje lokalitu zdroja a hovorí tak našej aplikácii, KAM sa má pozrieť, query parameter ("dotazovací parameter") sa používa na posielanie a filtrovanie dát vo vnútri požiadavky. Hovorí aplikáciu AKO sa pozrieť do určitého zdroja. Užívateľský vstup (query) je poslaný ako premenná do query parametra, ktorý je od URL oddelený otáznikom. Query parametre možno tiež reťaziť. Oddeľujú sa od seba pomocou znaku apersand (&). Napríklad v URL https://example.com/movies/?id=1&movie_name=Star%20Wars posielame otázky na id, ktoré sa má rovnať 1, a movie_name, ktoré sa má rovnať Star Wars. Query parametre nie sú povinnou súčasťou požiadavky na server, pomáhajú však získať podrobnejšie či presnejšie dáta.

Kombinácia znakov %20 v URL znamená medzeru.

Ukážme si, ako sa oba typy parametrov definujú v aplikáciách vytvorených pomocou FastAPI.

Path parametre

Začneme tým, že si parameter path vyskúšame na našej aplikácii Hello World. Aplikáciu si otvoríme v IDE. V termináli ju potom spustíme:

Od minule pribudla v príkaze na spustenie servera časť --reload. Vďaka nej server sleduje zmeny v kóde uvedeného zdroja a pokiaľ nejaké zaznamená, automaticky obnoví stránku, čo sa pri vývoji skvele hodí.

Aplikácia sa spustí na localhostu ( http://127.0.0.1:8000/). Otvoríme si ju v prehliadači.

V IDE otvoríme jej súbor main.py a prepíšeme funkciu index(). Funkcia sa bude novo volať read_movie(). Ako argument prijme path parameter movie_id a vráti nám film so zodpovedajúcim id:

Syntax pripomína formátovaný reťazec. Hodnota path parametra movie_id (v dekorátore funkcie je uvedená v zložených zátvorkách) je dynamická a bude poslaná do funkcie ako argument movie_id v závislosti od požiadavky užívateľa.

Adresu localhostu doplníme o /movies/1 tak, aby vyzerala takto: http://127.0.0.1:8000/movies/1. Potvrdíme stlačením Enter a vypíše sa nám:

Pokiaľ budeme meniť poslednú číslicu v URL, bude sa zodpovedajúcim spôsobom meniť aj id zobrazené na stránke.

Typové anotácie a ich prednosti

FastAPI vie prijímať aj typové anotácie. Nie sú povinné, ale ide o dobrú prax, ktorú budeme dodržiavať. Má to iba výhody. Definíciu funkcie read_movie() upravíme takto:

Definovali sme, že funkcia read_movie() prijme ako parameter movie_id iba typ int. Tento nepatrný prípisok má veľké dôsledky. Vďaka nemu nám naše IDE ponúknu najrôznejšiu podporu vo vnútri takej funkcie, napríklad skontrolujú chyby, ponúknu automatické dokončenie a pod. Navyše, ak teraz navštívime http://127.0.0.1:8000/movies/1, všimneme si, že sa nám tentoraz vypísalo

Áno, id filmu sa pošle a vráti ako int, nie ako str v predchádzajúcom variante. Takže tým, že deklarujeme typ parametra, nám FastAPI ku všetkým skôr menovaným výhodám pridá ešte automatické parsovanie a taktiež validáciu dát. Keby sme totiž skúsili navštíviť napríklad http://127.0.0.1:8000/movies/jedna, vráti sa nám celkom podrobné chybové hlásenie upozorňujúce na nemožnosť spracovať str namiesto int, ktorý daná funkcia vyžaduje:

Query parametre

Odoslanie požiadavky na konkrétne dáta máme vyriešené a prejdeme teda na filtrovanie dát. Najskôr si vytvoríme malú improvizovanú databázu, nech máme v čom hľadať. Ako databáza nám poslúži slovník obsahujúci niekoľko ďalších slovníkov s údajmi o filmoch a ich režiséroch. Stále pre jednoduchosť pracujeme v main.py:

Naša funkcia pre vyhľadávanie filmov podľa parametrov sa bude volať find_movie. Dekorátor a hlavička funkcie bude podobná tej predchádzajúcej, ale telo sa bude líšiť. Upravme teda funkciu ešte raz:

Všimnime si, že v dekorátore tentokrát chýba dynamický path parameter movie_id a URL končí pevným parametrom /movies/. Naša funkcia prijíma parameter movie_name vo formáte str. Do premennej result sme si uložili chybovú hlášku pre prípad, že sa vyhľadávanie nepodarí. Potom prejdeme pomocou for cyklu našu improvizovanú databázu a pokiaľ v nej požadované meno filmu prevedené na malé znaky nenájdeme, vrátime užívateľovi pripravenú chybovú správu. Pokiaľ uspejeme, vrátime upravenú správu obsahujúcu id filmu a jeho detaily v podobe názvu a režiséra a ukončíme cyklus, pretože je zbytočné pokračovať v hľadaní.

Ak si teraz otvoríme http://localhost:8000/movies/?movie_name=Frozen, dostaneme späť:

Rôzne prehliadače si výstup formátujú po svojom. Takto v riadku ho zobrazia Opera a Chrome, no a Edge si ho rozložia na sedem riadkov. Na to treba myslieť a výstup do prehliadača prípadne naformátovať nútene pomocou JavaScriptu alebo HTML šablóny. Oboje si ukážeme ďalej v kurze.

Voliteľné parametre a východiskové hodnoty

Vo vyhľadávaní sa rozhodne nemusíme obmedzovať na jeden parameter. Nestačí ale iba pripísať ďalší parameter do funkcie, musíme z nich tiež urobiť nepovinné parametre. To docielime tým, že u nich umožníme zadať hodnotu None a definujeme jej východiskovú hodnotu. Pridajme si vyhľadávanie podľa režiséra:

Znak "|" na slovenskej klávesnici napíšeme pomocou AltGr + W

Parametre našej funkcie sú teraz movie_name a director, oboje typu str alebo None. V prípade, že ich užívateľská požiadavka nebude obsahovať (teda parametre budú mať hodnotu None), použije funkcia východiskovú hodnotu, čo je v oboch prípadoch None (preto zápis None = None, pokiaľ nie je zadaná hodnota, je None).

Telo funkcie sme tiež upravili, aby stačilo v databáze nájsť iba jeden zo záznamov a vrátil sa správny výsledok. Pokiaľ budú oba parametre None (teda pri pokuse o navštívenie http://localhost:8000/movies/), hľadanie v databáze ani neprebehne a vráti sa hneď správa o nenájdení filmu.

Ak teraz navštívime http://localhost:8000/movies/?movie_name=Shrek alebo http://localhost:8000/movies/?director=Vicky%20Jenson, uvidíme v oboch prípadoch zhodne:

Zdrojový kód je opäť priložený v archíve na konci lekcie.

V budúcej lekcii, Endpointy a automatická dokumentácia vo FastAPI , si ukážeme POST, PUT a DELETE endpointy vo FastAPI a vyskúšame si prácu s automatickou dokumentáciou.