Logo STC

Vytvoření a správa API pomocí Azure Functions

Azure Programming26. 10. 2023

#API#postup#představení#studenti#VisualStudio

V tomto článku se dozvíte, jak si vytvořit vlastní API přes Azure Functions ve Visual Studiu a také, jak přes API Managment můžete své funkce spravovat.

Co vlastně API je?

API (Application Programming Interface) je rozhraní pro programování aplikací. Používá se především pro komunikaci mezi programy. V našem případě budeme používat Azure Functions jako backend (logika naší aplikace), API Managment pro správu celé API a její testování. Na níže uvedeném obrázku můžete vidět schéma tohoto projektu.

Obrázek se schématem projektu. Ukazuje cestu našeho požadavku všemi službami kterými prochází.
Obrázek se schématem projektu. Ukazuje cestu našeho požadavku všemi službami kterými prochází.

Výstup API

API nám může vracet několik hodnot. Mezi základní patří HTTP status codes. Ty mají pět kategorií, zde si ukážeme tři nejvíce používané a u každé jeden ukázkový response.

  • 2xx (Success) [200 OK] - standartní odpověď, že HTTP požadavek byl úspěsný.
  • 4xx (Client Error) [404 Not Found] - server nemůže najít požadovaný soubor.
  • 5xx (Server Error) [500 Internal Server Error] - při zpracování requestu došlo k nespecifikované chybě.

Dále API může vracet hodnoty v podobě JSONu, XML nebo jednoduchého textu.

JSON { "jmeno": "Jakub", "vek": 17 }

XML Jakub 17

Vytvoření API

K vytvoření vlastní API je potřeba:

Postup pro backend

Otevřete si Azure portál, na hlavní stránce Azure si kliknete na Skupiny prostředků a vytvoříte novou.

Screenshot z Azure portálu při vytváření nové skupiny prostředků.
Screenshot z Azure portálu při vytváření nové skupiny prostředků.

Vyplníte podrobnosti o projektu –⁠ vyberete předplatné, pojmenujete Skupinu prostředků a vyberete oblast. Až budete mít všechno vyplněné, dole kliknete na Zkontrolovat a vytvořit a skupina prostředků by se Vám měla úspěšně vytvořit. Ověřit si to můžete tak, že vpravo nahoře by Vám mělo vyskočit oznámení o úspěšném vytvoření.

Screenshot z Azure portálu při nastavení vytváření skupiny prostředků.
Screenshot z Azure portálu při nastavení vytváření skupiny prostředků.
Screenshot z Azure portálu oznámení o úspěšném vytvoření skupiny prostředků.
Screenshot z Azure portálu oznámení o úspěšném vytvoření skupiny prostředků.

Otevřete si skupinu prostředků, a kliknete nahoře v panelu na vytvořit.

Screenshot z Azure portálu při vytváření nového prostředku.
Screenshot z Azure portálu při vytváření nového prostředku.

Do vyhledávání zadáte "API Managment" a kliknete na vytvořit.

Screenshot z Azure portálu při vytváření API Managment prostředku.
Screenshot z Azure portálu při vytváření API Managment prostředku.

Vyplníte informace –⁠ předplatné, název a ostatní. Dole si můžete všimnout cenové úrovně, ze kterých si lze vybrat. Dělí se především podle SLA. To je smlouva mezi poskytovatelem služby a uživatelem. Procenta uvedená u cenové úrovně znamenají, jak dlouho musí být služba dostupná za celou dobu, co běží. Po vyplnění můžeme kliknout opět na zkontrolovat a vytvořit.

Screenshot z Azure portálu při nastavování API Managmentu.
Screenshot z Azure portálu při nastavování API Managmentu.

Kontrola vytvořených služeb

Po vytvoření by Vám opět mělo vyjet oznámení o úspěšném vytvoření. Jako další se vrátíme zpět do skupiny prostředků, a dle tohoto článku si vytvoříte novou Azure Function.

Pokud jste udělali vše správně, měli byste ve vaší skupině prostředků vidět následující služby. Jak si můžete všimnout, vytvořily se nám automaticky ještě nové prostředky.

Screenshot z Azure portálu obsahu skupiny prostředků.
Screenshot z Azure portálu obsahu skupiny prostředků.

Vytvoření vlastní funkce pomocí Visual Studia

Visual Studio má tři edice:

  • Community (zdarma ke stažení) –⁠ pouze pro individuální developery, výuku a další.
  • Professional (placená) –⁠ pro komerční účely.
  • Enterprise (placená) –⁠ pro komerční účely, a firmy s větším počtem zaměstnanců než 250 nebo firmy s ročním příjmem přesahující 1 milion dolarů.

Podrobněji je můžete prozkoumat na stránkách Visual Studia. K tomuto projektu Vám však bude stačit bezplatná edice Community.

Nyní otevřete Visual Studio a vytvoříte nový projekt. Vyberete Azure Functions, následně HTTP trigger a aplikaci vytvoříte.

Screenshot z Microsoft Visual Studia při vytváření nového projektu Azure Functions.
Screenshot z Microsoft Visual Studia při vytváření nového projektu Azure Functions.

Jestli nemáte na výběr Azure Functions, musíte si jej přidat v installeru. Spustíte program Visual Studio Installer a kliknete na změnit. Následně přidáte Azure –⁠ vývoj a kliknete na změnit.

Screenshot z Microsoft Visual Studio Installeru při přidávání Azure SDK.
Screenshot z Microsoft Visual Studio Installeru při přidávání Azure SDK.
Screenshot z Microsoft Visual Studio Installeru při přidávání Azure SDK.
Screenshot z Microsoft Visual Studio Installeru při přidávání Azure SDK.

Pokud jste udělali vše správně, vytvořený projekt by měl vypadat následovně. Můžete si vyzkoušet funkčnost. Pomocí klávesy F5 spustíte program, a měla by Vám vyjet konzole ve které uvidíte následující informace. Pokud otevřete uvedený localhost, měli by jste vidět text napsaný z již hotového kódu.

Screenshot z Microsoft Visual Studia projektu a kódu.
Screenshot z Microsoft Visual Studia projektu a kódu.
Screenshot konzole která vypisuje informace o vytvořené funkci.
Screenshot konzole která vypisuje informace o vytvořené funkci.

Kód si samozřejmě můžete upravit jak jen chcete podle vašeho nápadu. Já jsem si vybral pro příklad fiktivní API firmy, která nám bude vracet list zaměstnanců a jejich údaje. Změníte následující části kódu a ten bude vypadat následovně. Opět můžete pomocí F5 spustit a zkontrolovat, zda výstup vypadá následovně.

Poznámka: Následující kódy lze najít na na githubu.

using System; using System.IO; using System.Threading.Tasks; using Microsoft.AspNetCore.Mvc; using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Extensions.Http; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; using Newtonsoft.Json; namespace API_Tutorial { public static class Function1 { [FunctionName("Zamestnanci")] public static async Task Run( [HttpTrigger(AuthorizationLevel.Function, "get", Route = "zamestnanci")] HttpRequest req, ILogger log) { // Zaznamená do konzole že se spustila funkce log.LogInformation("C# HTTP trigger function processed a request."); // Vytvoří údaje o zaměstnancích dynamic zamestnanci = new object[] { new { jmenoZamestnance = "Jan", plat = 26300, pozice = "Brigádník" }, new { jmenoZamestnance = "Petr", plat = 32500, pozice = "Majitel firmy" } }; // Vrátí Status200OK a informace o zaměstnancích return new OkObjectResult(zamestnanci); } } }

Výstup v JSONu z této API vypadá následovně:

[{"jmenoZamestnance":"Jan","plat":26300,"pozice":"Brigádník"},{"jmenoZamestnance":"Petr","plat":32500,"pozice":"Majitel firmy"}]

Jako další příklad jsem vytvořil API, která vrací odpočet do začátku letních prázdnin. Vytvoříte novou funkci a můžete do ní vložit níže uvedený kód.

using System; using System.IO; using System.Threading.Tasks; using Microsoft.AspNetCore.Mvc; using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Extensions.Http; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; using Newtonsoft.Json; namespace odpocetPrazdnin { public static class Function1 { [FunctionName("Prazdniny")] public static async Task Run( [HttpTrigger(AuthorizationLevel.Function, "get", Route = "prazdniny")] HttpRequest req, ILogger log) { // Zaznamená do konzole že se spustila funkce log.LogInformation("C# HTTP trigger function processed a request."); // Proměnné pro naše datumy které potřebujeme DateTime zacatekPrazdnin = DateTime.Parse("1/7/2022 00:00:00 AM"); DateTime aktualniCas = DateTime.Now; // Vypočítá rozdíl a vrátí ho TimeSpan rozdil = zacatekPrazdnin - aktualniCas; string response = string.Format("Do začátku prázdnin zbývá {0} dní, {1} hodin, {2} minut, {3} sekund", rozdil.Days, rozdil.Hours, rozdil.Minutes, rozdil.Seconds); return new OkObjectResult(response); } } }

Výstup bude opět vypadat následovně. V tomto případě ale nebude program vracet hodnotu v JSONu, ale v obyčejném textu.

Screenshot z výstupu naší API v prohlížeči.
Screenshot z výstupu naší API v prohlížeči.

Nahrání funkce na Azure

Nyní máte úspěšně vytvořenou funkci a nahrajete ji na Azure. Pravým tlačítkem kliknete na Solution Explorer, a kliknete na Publish.

Screenshot z Microsot Visual Studia publikace projektu.
Screenshot z Microsot Visual Studia publikace projektu.

Vyberete Azure, následně Azure Function App (Windows), a vyberete vaší Resource Group (skupinu prostředků) a dáte Publish. Pokud se vše povedlo, měli byste vidět Publish succeeded.

Screenshot z Microsot Visual Studia publikace projektu.
Screenshot z Microsot Visual Studia publikace projektu.
Screenshot z Microsot Visual Studia publikace projektu.
Screenshot z Microsot Visual Studia publikace projektu.
Screenshot z Microsot Visual Studia publikace projektu.
Screenshot z Microsot Visual Studia publikace projektu.

Postup pro vytvoření API

Nyní, když máte vytvořený backend pro naší API, ji můžete konečně vytvořit. Najedete na vytvořený API Managment, kliknete na levém panelu Rozhraní API a vytvoříte novou z Function App.

Screenshot z Microsoft Azure portálu při vytváření API z Function App.
Screenshot z Microsoft Azure portálu při vytváření API z Function App.

Po kliknutí na vytvoření API z Function App Vám vyjede okno, kde musíte importovat vaší funkci. Dáte vybrat, a vybere vaší vytvořenou funkci a dole dáte opět vybrat.

Screenshot z Microsoft Azure portálu při importování naší vytvořené funkce.
Screenshot z Microsoft Azure portálu při importování naší vytvořené funkce.

Nyní by vyplněné údaje měli vypadat takto. Dáte vytvořit.

Screenshot z Microsoft Azure portálu při vytváření API z Function App.
Screenshot z Microsoft Azure portálu při vytváření API z Function App.

Takhle vypadá Vaše momentálně vytvořená API. Vidíte tam následující údaje:

  • Cestu k API (v tomto případě /Zamestnanci)
  • Inbound processing - zde můžete změnit request předtím než se zpracuje v backendu. Lze přidat Limit call rate, Cache Responses a mnoho dalších.
  • Backend - zde můžeme vidět naší vytvořenou funkci.
  • Outbound processing - zde můžeme měnit response předtím než se odešle uživateli.
Screenshot z Microsoft Azure portálu při nastavování API, konkrétně Inbound, outbound processingu a backendu.
Screenshot z Microsoft Azure portálu při nastavování API, konkrétně Inbound, outbound processingu a backendu.

V Inbound processingu si můžete zapnout třeba již zmíněný Limit call rate. Ten omezí uživateli posílat příliš mnoho requestů za určitý čas. Na obrázku je nastaveno, že může být posláno pouze 1000 requestů za jednu minutu. Counter key je klíč, kterým když bude request poslán, limit call rate bude ignorován.

Screenshot z Microsoft Azure portálu při nastavování API, konkrétně inbound processingu.
Screenshot z Microsoft Azure portálu při nastavování API, konkrétně inbound processingu.

Pokud nakliknete na settings, můžete upravit mimo jiné to, zda je potřeba klíč k poslání requestu na stránku. Tyto klíče lze upravovat v sekci Předplatná.

Screenshot z Microsoft Azure portálu při nastavování API a potřebných klíčů.
Screenshot z Microsoft Azure portálu při nastavování API a potřebných klíčů.
Screenshot z Microsoft Azure portálu při nastavování klíčů k API.
Screenshot z Microsoft Azure portálu při nastavování klíčů k API.

Pokud jste vše správně nastavili, pokud se teď podíváte na první stránku, kterou lze vidět v nastavení API, měli byste vidět výstup z našeho backendu. Nezapomeňte na to, že pokud máte nastavené Subscription Needed, stránka Vám ukáže status code 401, neboť potřebujete poslat s requestem také klíč.

Screenshot z výstupu naší API na prohlížeči.
Screenshot z výstupu naší API na prohlížeči.

Deploy to Azure

Pokud kliknete na tlačítko níže, v Azure se Vám automaticky vytvoří stejný projekt jako jsem vytvořil já, a nemusíte se bát že pokazíte nějaký krok.

Závěr

Úspěšně jste vytvořili vlastní API s backendem vytvořeným přes Azure Functions. Vynalézavosti se meze nekladou, a tak lze Vaší vytvořenou funkci lehce upravit jak jenom chcete. Pomocí API Managmentu lze lehce upravit věci ohledně posílání requestů, např. již zmíněný Limit call rate, nebo třeba Filter IP Adress, kde si můžeme nastavit jaká IP Adresa může posílat request na naší API.