Zásady správného řízení rozhraní API

Dokončeno

Zásady správného řízení rozhraní API se definují jako postup definování a uplatňování standardů, zásad a procesů ve velkém měřítku napříč všemi rozhraními API organizace. Centrum rozhraní API vám to umožňuje s:

• Sledování metadat rozhraní API, včetně názvu rozhraní API, popisu, verzí, definic a nasazení Kromě toho můžete zadat vlastní metadata rozhraní API – například živé informace o webu, úložiště správy zdrojového kódu atd. – ke sledování metadat, která jsou pro vaši organizaci důležitá (viz předchozí modul).
• Zajištění, aby všechna rozhraní API byla navržena tak, aby odpovídala organizačním zásadám návrhu rozhraní API
• Zajištění včasné detekce verzí rozhraní API s zásadními změnami pro bezproblémové zavedení a komunikaci se spotřebiteli rozhraní API

V této lekci si ukážeme, jak vám centrum API umožňuje konfigurovat zásady správného řízení rozhraní API ve velkém měřítku.

Požadavky

Pokud chcete řídit rozhraní API pomocí služby API Center, budete muset:

1. Nainstalujte rozhraní příkazového řádku Azure CLI.
2. Nainstalujte Azure Developer CLI (azd).
3. Zaregistrujte ve svém předplatném poskytovatele prostředků Event Gridu. 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.

Shoda s návrhem rozhraní API

Týmy platformy API často zodpovídají za definování sady pokynů pro producenty rozhraní API. Centrum rozhraní API umožňuje kodifikovat pokyny k rozhraní API definováním pravidel pomocí opensourcového lintovacího modulu Spectral . Ve výchozím nastavení je součástí centra rozhraní API poskytnuté pravidlo Spectral, ale vždy můžete vytvářet vlastní nebo využívat velkou komunitu opensourcových sad pravidel. Pokaždé, když se nahraje definice rozhraní API, spustí Centrum rozhraní API linter s použitím poskytnuté sady pravidel a zkontroluje, jestli definice rozhraní API vyhovuje pravidlu. Vygeneruje se sestava dodržování předpisů rozhraní API, kterou můžete zobrazit v centru rozhraní API.

Konfigurace souladu s návrhem rozhraní API pro vaši organizaci:

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.

Zásady správného řízení rozhraní API s levým posunem

Mezi nejúspěšnější iniciativy zásad správného řízení vždy patří sami vývojáři. Díky použití tradičních principů posunu doleva můžou týmy platformy API zajistit, aby producenti rozhraní API přesně věděli, jaké požadavky musí splnit při publikování rozhraní API v rané fázi vývojového cyklu. To šetří cennou dobu vývoje tím, že snižuje potřebu napravit nekompatibilní rozhraní API později ve vývojovém cyklu.

Rozšíření API Center pro Visual Studio Code poskytuje výrobcům rozhraní API prostředí pro spouštění kontrol shody návrhu rozhraní API přímo v editoru Visual Studio Code při vytváření rozhraní API. Kromě toho můžou producenti rozhraní API pomocí funkce detekce zásadních změn zjistit, kdy změna může vést k přerušení chatu pro uživatele rozhraní API.

Shoda s návrhem rozhraní API v editoru Visual Studio Code

Rozšíření API Center je integrované se Spectral, linter JSON/YAML, který podporuje OpenAPI a vlastní sadu pravidel. Rozšíření umožňuje vývojářům striktně dodržovat poskytnuté nebo doporučené průvodce stylem rozhraní API a zajistit konzistenci napříč všemi rozhraními API, která se vyvíjejí napříč různými týmy.

Poznámka:

Abyste mohli tuto funkci používat, musíte nainstalovat rozšíření API Center a Spectral .

Chcete-li aktivovat,

1. K otevření palety příkazů použijte klávesovou zkratku Ctrl+Shift+P . Zadejte Azure API Center: Nastavte aktivní průvodce stylem rozhraní API a stiskněte Enter.
2. Vyberte jedno z výchozích pravidel, která jsou zadaná, nebo pokud má vaše organizace již k dispozici průvodce stylem, použijte k určení aktivní sady pravidel v editoru Visual Studio Code možnost Vybrat místní soubor nebo vstupní vzdálenou adresu URL . Stiskněte Enter.

Po nastavení aktivního průvodce stylem rozhraní API se otevřením libovolného souboru specifikace založeného na OpenAPI nebo AsyncAPI aktivuje místní operace lintování v editoru Visual Studio Code. Výsledky se zobrazí v editoru i v okně Problémy (Zobrazit > problémy nebo Ctrl+Shift+M).

Detekce zásadních změn v editoru Visual Studio Code

Verze rozhraní API pro odesílání, které přerušují produkční pracovní postupy příjemců, mají za následek nespolehlivosti a ztrátu důvěryhodnosti. Rozšíření API Center s využitím optického rozhraní umožňuje vývojářům snadno porovnat všechny dvě verze rozhraní API a detekovat všechny zásadní změny zavedené v rozhraní API před nasazením.

Poznámka:

Abyste mohli tuto funkci používat, musíte nainstalovat Aplikaci Optic. Nainstalujte ho pomocí následujícího příkazu.

npm install -g @useoptic/optic*

Potom můžete

1. K otevření palety příkazů použijte klávesovou zkratku Ctrl+Shift+P . Zadejte Azure API Center: Zjištění zásadní změny a stiskněte Enter.
2. Vyberte první dokument specifikace rozhraní API, který chcete porovnat. Mezi platné možnosti patří specifikace rozhraní API nalezené v centru rozhraní API, místní soubor nebo aktivní editor v editoru Visual Studio Code.
3. Vyberte druhý dokument specifikace rozhraní API, který chcete porovnat. Mezi platné možnosti patří specifikace rozhraní API nalezené v centru rozhraní API, místní soubor nebo aktivní editor v editoru Visual Studio Code.

Visual Studio Code otevře rozdílové zobrazení mezi dvěma specifikacemi rozhraní API. Všechny zásadní změny se zobrazí v editoru i v okně Problémy (Zobrazit > problémy nebo Ctrl+Shift+M).