Článek

Praktický úvod do služby Azure API Management Gateway: typy (SaaS vs. vlastní hostování), síťové připojení (veřejná síť/VNet/hybridní), tvorba API z OpenAPI/HTTP, zásady, testování a zabezpečení pomocí klíče předplatného.

Gateway (brána) v Azure API Management je komponenta, která funguje jako prostředník mezi klienty a backendovými službami. Jejím hlavním úkolem je přijmout požadavek od klienta, aplikovat definovaná pravidla (např. autentizace, limity, transformace) a následně požadavek přesměrovat do cílové služby.

K dispozici jsou dva hlavní typy brány:

• SaaS (hostovaná) brána – běží přímo v Azure jako součást služby API Management.
• Self-hosted brána – kontejnerizovaná verze brány, kterou můžete nasadit v on-premise prostředí, na jiné cloudové platformě nebo v edge lokalitách. Umožňuje tak jednotnou správu API i mimo Azure.

K čemu slouží API Management Gateway?

• Centralizovaná správa API – všechna volání API procházejí bránou, kde se uplatňují pravidla definovaná v politice (policy).
• Bezpečnost – podpora OAuth 2.0, filtrování IP adres, šifrované připojení, ověřování tokenů a ochrana proti zneužití.
• Transformace požadavků/odpovědí – možnost přepsat hlavičky, URL cesty, formát těla požadavku/odpovědi (např. z XML do JSON).
• Omezení rychlosti a škrcení – ochrana backendu před přetížením pomocí limitů požadavků.
• Monitorování a protokolování – integrované nástroje pro sledování využití API a identifikaci problémů.
• Verzování a publikování API – možnost spravovat různé verze API, publikovat testovací a produkční prostředí.

Kde se Azure API Management hodí?

• Pro organizace s více interními a externími API, které potřebují jednotný přístup a dohled.
• Firmy, které potřebují zajistit komunikaci mezi frontendovými aplikacemi a backendovými systémy.
• Scénáře, kde se kombinuje on-premise infrastruktura s cloudovými službami.
• Projekty s požadavkem na monetizaci API, monitorování nebo bezpečný přístup pro třetí strany.

Úvod do moderní správy API

V době, kdy aplikace nabývají na složitosti a stále více služeb komunikuje prostřednictvím API rozhraní, se centrální správa těchto rozhraní stává nezbytností. Právě k tomuto účelu slouží API Gateway – komponenta, která funguje jako jednotný vstupní bod pro všechna volání směřující do backendových služeb.
 

Na obrázku výše vidíme typický scénář využití API Gateway:

• Actor (uživatel nebo klientská aplikace) odesílá požadavky.
• Požadavky procházejí přes API GW (API Gateway) – tato brána nejprve zajistí autentizaci uživatele nebo aplikace.
• Po úspěšném ověření identit API Gateway následně přesměruje požadavek na příslušný backend (např. mikroslužbu, databázi, REST API atd.).

Jak nainstalovat a nakonfigurovat Azure API Gateway (API Management)

Krok 1 – Přihlášení do portálu Azure

Prvním krokem je přihlášení do portálu https://portal.azure.com.

Krok 2 – Vytvoření nové služby API Management

Klikněte na „Create a resource“ (vlevo nahoře).
Vyhledejte API Management.
Klikněte na API Management a poté na „Create“.

Krok 3 – Vyplnění parametrů služby

Ve formuláři vyplňte následující pole:

• Subscription – vyberte aktivní předplatné.
• Resource group – vyberte existující skupinu zdrojů nebo vytvořte novou (např. api-gw-group).
• Resource Name – zadejte název služby (např. moja-api-gateway).
• Region – vyberte preferovaný geografický region (např. West Europe).
• Organization name – zadá se název organizace nebo týmu.
• E-mail správce – zadejte e-mailovou adresu správce, na kterou budou zasílány oznámení.

Po vyplnění údajů pokračujte kliknutím na „Review + create“ a následně na „Create“, čímž se spustí nasazení služby.

Sekce Networking v Azure API Management – možnosti a nastavení konektivity

Služba Azure API Management (APIM) nabízí několik způsobů, jak může být API Gateway zpřístupněna klientským aplikacím – buď veřejně přes internet, nebo soukromě pouze v rámci zabezpečeného síťového prostředí. Volba režimu připojení má zásadní vliv na bezpečnost, architekturu a způsob integrace řešení.

1. External (veřejná konektivita)

• API Gateway je dostupná prostřednictvím veřejné IP adresy – přístupná z internetu bez nutnosti speciálního síťového připojení. Použití:
  • Webové/mobilní aplikace běžící mimo Azure
  • Externí partneři nebo zákazníci
  • Rychlé testování nebo vývoj Interní (vnitřní připojení – VNet Integration)

2. Přístup pouze z Azure Virtual Network

• Brána běží v soukromém režimu – dostupná pouze pro zdroje ve stejné síti VNet nebo přes soukromé připojení (např. VPN, ExpressRoute). Použití:
  • Systémy s citlivými daty
  • Firemní API rozhraní nepřístupná z veřejného internetu
  • Hybridní scénáře (on-premise + cloud)

3. Hybridní model – kombinace Public + VNet

• Některé části API mohou být veřejné (např. otevřené API pro třetí strany), jiné pouze pro interní systémy. Možné v režimu Premium Tier, kde lze konfigurovat více regionálních instancí a smíšenou konektivitu. Použití:
  • Velké organizace s různými požadavky na přístup
  • API rozhraní pro veřejnost i interní týmy
     

Krok 1: Vytvoření virtuální sítě Azure

Pokud ještě není vytvořena virtuální síť, je třeba ji zřídit následujícím způsobem:

1. V prostředí Azure Portal vyberte možnost Create a resource.
2. Do vyhledávacího pole zadejte výraz „Virtual Network“ a vyberte příslušnou službu.
3. Síti se přiřadí název (např. apim-vnet).
4. V části „IP Addressing“ přidejte rozsah adres, například 10.1.0.0/16.
5. V sekci Subnets vytvořte podsíť s názvem apim-subnet, například 10.1.0.0/24.

Krok 2: Zřízení veřejné IP adresy

Následně je třeba vytvořit veřejnou IP adresu, která bude sloužit jako vstupní bod pro příchozí požadavky:

1. V portálu Azure opět vyberte možnost „Create a resource“.
2. Vyhledejte službu „Public IP address“.
3. IP adrese se přiřadí název (např. apim-public-ip).
4. V části SKU vyberte možnost Standard (vyžadováno při integraci s VNet).
5. V sekci „Assignment“ vyberte možnost „Static“ – IP adresa se po vytvoření nebude měnit.

Tato veřejná IP adresa bude později přiřazena ke službě API Management a bude sloužit jako veřejný přístupový bod pro klienty.

Krok 3: Přiřazení sítě VNet a veřejné IP adresy ke službě APIM

Po vytvoření sítě a IP adresy dokončete konfiguraci následujícím způsobem:

1. V portálu Azure otevřete existující službu API Management (APIM).
2. V levém menu přejděte do části Network → Virtual Network → Configure.
3. Zvolte režim External.
4. Vyberte vytvořenou síť apim-vnet a podsíť apim-subnet.
5. V sekci Public IP address vyberte adresu apim-public-ip.
6. Změny potvrďte kliknutím na Apply.
7. Poznámka: Změna může trvat 15–45 minut.

Jak vytvořit API v Azure API Management

Po nasazení API Gateway do Azure API Management (APIM) je dalším krokem vytvoření samotného API rozhraní, přes které budou procházet požadavky od klientů a aplikací. APIM umožňuje snadno vytvořit nové API nebo importovat již existující specifikace (např. OpenAPI / Swagger / WSDL).

Možnosti vytvoření API

V prostředí Azure API Management lze API rozhraní vytvořit několika způsoby:

• Import stávající specifikace OpenAPI (Swagger)
• Import služby SOAP na základě definice WSDL
• Propojení se stávající službou v Azure App Service nebo Azure Functions
• Vytvoření prázdného API (Blank API) a ruční přidání operací

Krok 1: Otevřete Azure API Management a přejděte do sekce „APIs“

1. V portálu Azure se otevře vytvořená služba API Management.
2. V levém navigačním panelu klikněte na položku „APIs“.
3. Pro přidání nového API vyberte možnost „+ Add API“ nebo „Create from scratch“, v závislosti na preferovaném způsobu vytvoření rozhraní.

Na obrázku výše je zobrazeno rozhraní pro návrh a úpravy API ve službě Azure API Management. Jedná se o prostor, ve kterém se konfiguruje chování API brány – včetně zpracování příchozích požadavků, úprav odpovědí, definování jednotlivých operací a aplikace zásad (policies). Pomocí tohoto rozhraní je možné podrobně řídit způsob, jakým jsou požadavky od klientů zpracovávány ještě před jejich odesláním na backend, a také upravovat odpovědi před jejich vrácením klientovi.

Rozhraní je rozděleno do čtyř hlavních sekcí (zleva doprava):

1. Navigační panel (levá strana)

• Search APIs / operations – umožňuje vyhledávat v seznamu vašich API nebo jejich operací.
• Add API – tlačítko pro přidání nového API do služby.
• All APIs – seznam všech API, která jste vytvořili.
• V příkladu je zobrazeno Echo API – vzorové/testovací API dostupné po instalaci.

2. Definice operace ve frontendu

• Zobrazuje podrobnosti aktuální operace, v tomto případě:
  • GET /resource
  • Operace má dotazové parametry: param1 (řetězec) a param2 (číslo)
• Odpověď operace je označena jako 200 OK (úspěšná odpověď).
• Zde se definuje:
  • Metoda (GET, POST atd.)
  • Cesta (/resource)
  • Parametry
  • Typ odpovědi (např. JSON, XML)

3. Zpracování příchozích požadavků

• Tato sekce definuje, co se má stát s požadavkem od klienta, než bude odeslán na backend.
• Zde se definují zásady (policies), jako například:
  • Ověření JWT tokenu (validate-jwt)
  • Omezení počtu přístupů (rate-limit)
  • Úprava hlaviček nebo URL (rewrite-uri, set-header)
• Na obrázku vidíme, že zde je přidána základní politika označená jako base.

4. Sekce Backend

• Zobrazuje HTTP(S) endpoint, kam má být požadavek směrován.
• V tomto případě: http://echoapi.cloudapp.net/api
• To znamená, že požadavky, které projdou bránou, se odesílají na tento backend.
• V této části lze přidat politiky, například pro úpravu URL adresy nebo pro zabezpečení požadavků.

5. Outbound processing (výstupní zpracování)

• Tato sekce určuje, jak má být odpověď z backendu upravena před odesláním klientovi.
• Příklady použití:
  • Odstranění nebo přidání hlaviček
  • Převod XML na JSON
  • Protokolování odpovědí
• Na obrázku je použita základní politika „base“.

Vytvoření nového HTTP API

Na obrázku výše vidíme formulář, který se zobrazí po kliknutí na „+ Add API“ a následném výběru možnosti HTTP API. Tento formulář slouží k základnímu nastavení nového API rozhraní, které bude zpřístupněno prostřednictvím API Gateway.

Níže jsou uvedeny popisy jednotlivých polí:

1. Display name:

• Zobrazovaný název API, který se zobrazí v rozhraní APIM.
• Může být libovolný – v tomto případě:
  • Vrací IP adresu žadatele

2. Název:

• Interní identifikátor API – používá se v URL a v systémových záznamech.
• Automaticky se generuje z názvu, ale můžete jej upravit (např. bez mezer, malá písmena).
• V příkladu:
  • returns-the-requester-s-ip-address

3. Popis:

• Krátký popis API – nepovinný, ale doporučený pro přehlednost.
• Zde slouží k vysvětlení účelu:
  • Vrací IP adresu žadatele

4. URL webové služby:

• Nejdůležitější pole – sem zadáte skutečnou URL adresu backendové služby, kam má být požadavek směrován.
• V tomto případě se jedná o veřejně dostupné testovací API:
  • https://httpbin.org

5. Schéma URL:

• Zvolíte, zda bude API fungovat přes HTTP, HTTPS nebo obojí.
• Pro zabezpečenou komunikaci se doporučuje používat pouze HTTPS.

6. Přípona URL API:

• Přípona, která se připojí k doméně APIM – tvoří konečnou adresu API.
• Např. pokud zvolíte ip, výsledný endpoint bude:
  • https://mhi...api.azure-api.net/ip

7. Základní URL (automaticky vygenerovaná):

• Základní adresa vaší brány API Management – nelze ji upravovat.
• V tomto případě:
  • https://mhi...azure-api.net

8. Štítky:

• Nepovinné pole – slouží ke kategorizaci a filtrování API.
• Užitečné při velkém počtu API (např. interní, externí, rezervace atd.)

9. Produkty:

• API musí být přiřazeno alespoň k jednomu produktu, jinak nebude zveřejněno.
• Produkt je „balíček“ API, který se poskytuje uživatelům (např. Free Tier, Premium APIs).

Přidání operace: GET /ip – návrh požadavku a odpovědi

Na obrázku výše vidíme obrazovku, na které právě probíhá konfigurace konkrétní operace API typu GET. Tato operace se nazývá Returns the requester's IP Address a bude sloužit k získání IP adresy volajícího klienta. Tento požadavek bude přesměrován na testovací službu https://httpbin.org/ip.

1. Zobrazovaný název:

• Interní identifikátor operace – bez mezer a diakritiky.
• Používá se v interních API exportech a systémových voláních.
• V příkladu:
  • returns-the-requester-s-ip-address

2. URL:

• Zde lze definovat:
  • Metodu: GET
  • Cestu: /ip
• Kombinací API suffixu a této cesty vznikne finální endpoint, například:
  • https://<tvoje-apim>.azure-api.net/ip

3. Sekce Responses:

• V této části se definují očekávané odpovědi od backendu, které jsou zpracovávány bránou (gateway).
• V tomto případě je definována odpověď:
  • Kód stavu: 200 OK
  • Popis (vpravo) – zatím prázdný, ale může obsahovat příklad odpovědi ve formátu JSON, schéma nebo poznámky.

Jak otestovat API pomocí příkazu cURL

Po vytvoření a nasazení API ve službě Azure API Management je vhodné provést testování mimo portál – například prostřednictvím příkazového řádku pomocí nástroje cURL.

Ve výchozím nastavení vyžaduje služba Azure API Management, aby byl každý požadavek autorizován pomocí tzv. subscription key. Tento klíč se přidává buď ve formě HTTP hlavičky (Ocp-Apim-Subscription-Key), nebo jako parametr přímo v URL (?subscription-key=...).

Je-li však povolen anonymní přístup, lze API testovat i bez použití předplatitelského klíče. Tento režim se využívá zejména u veřejně dostupných API rozhraní nebo pro účely testování.

Zapnutí ověřování pomocí předplatitelského klíče

Azure API Management umožňuje několik způsobů ověřování požadavků směřujících na publikované API. Výběr konkrétní metody závisí na bezpečnostních požadavcích, typu klienta i účelu samotného API (veřejné vs. interní). Ověřování zajišťuje, že API může volat pouze oprávněný uživatel nebo aplikace.

Subscription key (výchozí metoda) – Každé API lze zabezpečit pomocí tzv. subscription key, který se vkládá do požadavku: 

1. Buď do hlavičky HTTP:

• Ocp-Apim-Subscription-Key: <key>

2. Nebo jako parametr v URL:

• ?subscription-key=

Předplatitelský klíč ve službě Azure API Management je bezpečnostní token, který slouží k identifikaci a autorizaci klientů přistupujících k publikovaným rozhraním API. Jedná se o jednoduchý, ale účinný způsob zabezpečení API před neoprávněným přístupem. Klíč předplatného má podobu náhodně generovaného řetězce, obvykle o délce 32 až 40 znaků, například 1a2b3c4d5e6f7g8h9i0jklmnopqrstuv, a neobsahuje žádné speciální znaky.

Každý klíč je vázán na konkrétní předplatné (subscription), které patří k vybranému produktu v rámci služby APIM. Pro každé předplatné se automaticky generují dva klíče – primární a sekundární, přičemž jejich platnost je stejná a mohou být kdykoli obnoveny (regenerovány). Kromě autorizace požadavků umožňuje předplatitelský klíč také sledování spotřeby, uplatňování kvót, omezení rychlosti (rate limiting) a evidenci přístupu podle uživatelů nebo aplikací. V prostředí s více klienty nebo partnery poskytuje efektivní způsob správy a zabezpečení přístupu k rozhraní bez nutnosti složité autentizační logiky.

Další odborné články, návody a zajímavosti z oblasti IT najdete na webu: www.virtualall.sk