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

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.

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
<Osoba>
    <jmeno>Jakub</jmeno>
    <vek>17</vek>
</ Osoba>

Vytvoření API

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

• Účet na Azure
• Microsoft Visual Studio

Postup pro backend

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

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í.

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

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

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.

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.

• Plán služby App Service – ten definuje prostředky pro běh webové aplikace (originálně totiž Azure Functions vytváří webovou aplikaci – s tou my ale pracovat nebudeme)
• Služba API Management – námi vytvořená služba.
• Aplikace funkcí – námi vytvořená služba.
• Application Insights – služba která nám pomáhá monitorovat výkon webových aplikací.
• Účet úložiště – služba která poskytuje úložistě.

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.

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.

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.

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<IActionResult> 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<IActionResult> 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.

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.

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.

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.

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.

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

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.

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.

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á.

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íč.

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.