Povolení analýzy rozhraní API v centru rozhraní API – samoobslužná správa

Tento článek vysvětluje, jak povolit analýzu rozhraní API ve službě Azure API Center ručním nastavením modulu lintování a triggerů. Analýza rozhraní API nabízí možnosti lintování pro analýzu definic rozhraní API v centru rozhraní API vaší organizace. Linting zajišťuje, že definice rozhraní API odpovídají pravidlům stylu organizace a generují jednotlivé i souhrnné sestavy. Pomocí analýzy rozhraní API můžete identifikovat a opravit běžné chyby a nekonzistence v definicích rozhraní API.

Přehled scénáře

V tomto scénáři budete analyzovat definice rozhraní API ve vašem centru rozhraní API pomocí opensourcového lintovacího modulu Spectral . Aplikace Azure Functions spouští lintovací modul v reakci na události ve vašem centru rozhraní API. Spectral kontroluje, že rozhraní API definovaná v dokumentu specifikace JSON nebo YAML odpovídají pravidlům v přizpůsobitelné příručce stylu rozhraní API. Vygeneruje se sestava analýzy, kterou můžete zobrazit v centru rozhraní API.

Následující diagram znázorňuje kroky pro povolení lintování a analýzy ve vašem centru rozhraní API.

1. Nasaďte aplikaci Azure Functions, která spouští modul lintingu Spectral v definici rozhraní API.

2. Nakonfigurujte odběr událostí v Centru rozhraní Azure API tak, aby aktivoval aplikaci funkcí.

3. Událost se aktivuje přidáním nebo nahrazením definice rozhraní API v centru rozhraní API.

4. Při přijetí události aplikace funkcí vyvolá modul lintování Spectral.

5. Lintovací modul zkontroluje, že rozhraní API definovaná v definici odpovídají průvodci stylem rozhraní API organizace a vygenerují sestavu.

6. Zobrazte sestavu analýzy v centru rozhraní API.

Možnosti nasazení lintujícího modulu a odběru událostí

Tento článek obsahuje dvě možnosti nasazení lintovacího modulu a odběru událostí ve vašem centru rozhraní API:

• Automatizované nasazení – Použití Azure Developer CLI (azd) pro jednostupňové nasazení infrastruktury. Tato možnost se doporučuje pro zjednodušený proces nasazení.

• Ruční nasazení – Postupujte podle podrobných pokynů k nasazení aplikace Azure Functions a konfiguraci odběru událostí. Tato možnost se doporučuje, pokud dáváte přednost ručnímu nasazení a správě prostředků.

Omezení

• Linting aktuálně podporuje pouze soubory specifikace JSON nebo YAML, jako jsou dokumenty specifikace OpenAPI nebo AsyncAPI.
• Modul linting ve výchozím nastavení používá integrovanou spectral:oas sadu pravidel. Pokud chcete rozšířit sadu pravidel nebo vytvořit vlastní vodítka stylu rozhraní API, přečtěte si úložiště Spectral Na GitHubu.
• Aplikace funkcí Azure, která volá lintování, se účtuje samostatně a spravujete a udržujete ji.

Požadavky

• Centrum rozhraní API ve vašem předplatném Azure. Pokud jste ho ještě nevytvořili, přečtěte si článek Rychlý start: Vytvoření centra rozhraní API.

• Poskytovatel prostředků Event Gridu zaregistrovaný ve vašem předplatném. Pokud potřebujete zaregistrovat poskytovatele prostředků Event Gridu, přečtěte si téma Přihlášení k odběru událostí publikovaných partnerem ve službě Azure Event Grid.

• Pro Azure CLI:

  • Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.

    

  • Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

    • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.

    • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.

    • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

  Poznámka:

  az apic příkazy vyžadují apic-extension rozšíření Azure CLI. Pokud jste nepoužili az apic příkazy, můžete rozšíření nainstalovat dynamicky při spuštění prvního az apic příkazu nebo rozšíření nainstalovat ručně. Přečtěte si další informace o rozšířeních Azure CLI.

  Podívejte se na poznámky k verzi nejnovějších změn a aktualizací v nástroji apic-extension.

  Poznámka:

  Příklady příkazů Azure CLI v tomto článku se dají spustit v PowerShellu nebo prostředí Bash. Pokud je to potřeba kvůli jiné syntaxi proměnných, jsou pro tyto dvě prostředí k dispozici samostatné příklady příkazů.

azd nasazení aplikace Azure Functions a odběru událostí

Tato část obsahuje automatizované kroky pomocí Azure Developer CLI ke konfiguraci aplikace Azure Functions a odběru událostí, které umožňují lintování a analýzu ve vašem centru rozhraní API. Prostředky můžete také nakonfigurovat ručně.

Další požadavky pro tuto možnost

• Azure Developer CLI (azd)

Spuštění ukázky pomocí azd

1. Naklonujte úložiště GitHub a otevřete ho v editoru Visual Studio Code.

2. Změňte adresář na APICenter-Analyzer složku v úložišti.

3. resources/rulesets Ve složce najdete oas.yaml soubor. Tento soubor odpovídá vašemu aktuálnímu průvodci stylem rozhraní API a dá se upravit na základě potřeb a požadavků vaší organizace.

4. Ověřování pomocí Azure Developer CLI a Azure CLI pomocí následujících příkazů:

   azd auth login
   
   az login
   

5. Spuštěním následujícího příkazu nasaďte infrastrukturu linting do vašeho předplatného Azure.

   azd up
   

6. Podle pokynů zadejte požadované informace a nastavení nasazení, jako je název prostředí a název centra rozhraní API. Podrobnosti najdete v tématu Spuštění ukázky pomocí Azure Developer CLI (azd).

   Poznámka:

   Nasazení může trvat několik minut.

7. Po dokončení nasazení přejděte do centra rozhraní API na webu Azure Portal. V nabídce vlevo vyberte odběry událostí>a zobrazte tak vytvořené odběry událostí.

Do centra rozhraní API teď můžete nahrát definiční soubor rozhraní API, který aktivuje odběr událostí a spustí lintovací modul.

Ruční postup konfigurace aplikace Azure Functions a odběru událostí

Tato část obsahuje kroky ručního nasazení ke konfiguraci aplikace Azure Functions a odběru událostí pro povolení lintování a analýzy v centru rozhraní API. K automatizovanému nasazení můžete použít také Azure Developer CLI .

Další požadavky pro tuto možnost

• Visual Studio Code s rozšířením Azure Functions verze 1.10.4 nebo novějším

Krok 1. Nasazení aplikace Azure Functions

Nasazení aplikace Azure Functions, která spouští linting funkci v definicích rozhraní API:

1. Naklonujte úložiště GitHub a otevřete ho v editoru Visual Studio Code.

2. resources/rulesets Ve složce najdete oas.yaml soubor. Tento soubor odpovídá vašemu aktuálnímu průvodci stylem rozhraní API a dá se upravit na základě potřeb a požadavků vaší organizace.

3. Volitelně můžete aplikaci funkcí spustit místně a otestovat ji. Podrobnosti najdete v souboru README v úložišti.

4. Nasaďte aplikaci funkcí do Azure. Postup najdete v tématu Rychlý start: Vytvoření funkce v Azure pomocí TypeScriptu pomocí editoru Visual Studio Code.

   Poznámka:

   Nasazení aplikace funkcí může trvat několik minut.

5. Přihlaste se k webu Azure Portal a přejděte do aplikace funkcí.

6. Na stránce Přehled zkontrolujte následující podrobnosti:

   • Ověřte, že je spuštěná aplikace funkcí.
   • V části Funkce ověřte, že je funkce apicenter-analyzer povolená.

   

Krok 2. Konfigurace spravované identity v aplikaci funkcí

Pokud chcete aplikaci funkcí povolit přístup k Centru rozhraní API, nakonfigurujte pro aplikaci funkcí spravovanou identitu. Následující kroky ukazují, jak povolit a nakonfigurovat spravovanou identitu přiřazenou systémem pro aplikaci funkcí pomocí webu Azure Portal nebo Azure CLI.

Krok 3. Konfigurace odběru událostí v centru rozhraní API

Teď ve svém centru API vytvořte odběr událostí, který aktivuje aplikaci funkcí při nahrání nebo aktualizaci definičního souboru rozhraní API. Následující kroky ukazují, jak vytvořit odběr událostí pomocí webu Azure Portal nebo Azure CLI.

Aktivační událost v centru rozhraní API

Pokud chcete otestovat odběr událostí, zkuste nahrát nebo aktualizovat definiční soubor rozhraní API přidružený k verzi rozhraní API v centru rozhraní API. Nahrajte například dokument OpenAPI nebo AsyncAPI. Po aktivaci odběru událostí aplikace funkcí vyvolá modul linting rozhraní API k analýze definice rozhraní API.

• Podrobný postup přidání definice rozhraní API, verze rozhraní API a definice rozhraní API do centra rozhraní API najdete v tématu Kurz: Registrace rozhraní API v centru rozhraní API.
• Pokud chcete vytvořit rozhraní API nahráním definičního souboru rozhraní API pomocí Azure CLI, přečtěte si téma Registrace rozhraní API ze souboru specifikace.

Ověření, že se aktivovalo odběr událostí:

1. Přejděte do centra rozhraní API a v nabídce vlevo vyberte Události .

2. Vyberte kartu Odběry událostí a vyberte odběr událostí pro vaši aplikaci funkcí.

3. Zkontrolujte metriky a ověřte, že se aktivovalo odběr událostí a že se lintování úspěšně vyvolalo.

   

   Poznámka:

   Zobrazení metrik může trvat několik minut.

Po analýze definice rozhraní API vygeneruje modul linting sestavu na základě nakonfigurovaného průvodce stylem rozhraní API.

Zobrazení sestav analýzy rozhraní API

Sestavu analýzy definice rozhraní API můžete zobrazit na webu Azure Portal. Po analýze definice rozhraní API sestava uvádí chyby, upozornění a informace na základě nakonfigurovaného průvodce stylem rozhraní API.

Na portálu můžete také zobrazit souhrn analytických sestav pro všechny definice rozhraní API v centru rozhraní API.

Sestava analýzy pro definici rozhraní API

Zobrazení sestavy analýzy pro definici rozhraní API v centru rozhraní API:

1. Na portálu přejděte do verze rozhraní API ve vašem centru rozhraní API, kde jste přidali nebo aktualizovali definici rozhraní API.
2. V nabídce vlevo v části Podrobnosti vyberte Definice.
3. Vyberte definici rozhraní API, kterou jste nahráli nebo aktualizovali.
4. Vyberte kartu Analýza.

Otevře se sestava analýzy rozhraní API a zobrazí definici rozhraní API a chyby, upozornění a informace na základě nakonfigurovaného průvodce stylem rozhraní API. Následující snímek obrazovky ukazuje příklad sestavy analýzy rozhraní API.

Souhrn analýzy rozhraní API

Zobrazení souhrnu analytických sestav pro všechny definice rozhraní API v centru rozhraní API:

1. Na portálu přejděte do centra rozhraní API.

2. V nabídce vlevo v části Zásady správného řízení vyberte Analýzu rozhraní API. Zobrazí se souhrn.

   

Související obsah

Další informace o Event Gridu:

• Povolení analýzy rozhraní API v Centru rozhraní API – spravovaná Microsoftem
• Systémová témata ve službě Azure Event Grid
• Doručování nabízených oznámení event Gridu – koncepty
• Schéma Event Gridu pro Azure API Center