API-governance

Voltooid

API-governance wordt gedefinieerd als de praktijk voor het definiëren en toepassen van standaarden, beleidsregels en processen op schaal in alle organisatie-API's. Met API Center kunt u dit doen met:

• Api-metagegevens bijhouden, waaronder API-titel, beschrijving, versies, definities en implementaties. Daarnaast kunt u uw eigen aangepaste API-metagegevens opgeven, zoals livesitegegevens, opslagplaats voor broncodebeheer, enzovoort, om metagegevens bij te houden die belangrijk zijn voor uw organisatie (weergegeven in een eerdere module).
• Ervoor zorgen dat alle API's zijn ontworpen om te voldoen aan de organisatie-API-ontwerpfilosieën
• Zorgen voor tijdige detectie van API-versies met belangrijke wijzigingen voor naadloze implementaties en communicatie met API-consumenten

In deze les zien we hoe u met API Center API-governance op schaal kunt configureren.

Vereisten

Als u uw API's wilt beheren met API Center, moet u het volgende doen:

1. Installeer de Azure CLI.
2. Installeer de Azure Developer CLI (azd).
3. Registreer de Event Grid-resourceprovider in uw abonnement. Als u de Event Grid-resourceprovider moet registreren, raadpleegt u Abonneren op gebeurtenissen die zijn gepubliceerd door een partner met Azure Event Grid.

Api-ontwerpconformance

API-platformteams zijn vaak verantwoordelijk voor het definiëren van een set richtlijnen voor API-producenten. Met API Center kunt u API-richtlijnen codificeren door regels te definiëren met de opensource-linting-engine van Spectral . API Center wordt standaard geleverd met een meegeleverde Spectral-regel, maar u kunt altijd uw eigen regel bouwen of gebruikmaken van de grote community met opensource-regelsets. Telkens wanneer een API-definitie wordt geüpload, voert API Center de Spectral linter uit met behulp van de opgegeven regelset om de API-definitie te controleren op overeenstemming met de regel. Er wordt een rapport gegenereerd over API-naleving dat u kunt bekijken in uw API-centrum.

Ga als volgende te werk om de api-ontwerpconformance voor uw organisatie te configureren:

1. Kloon de GitHub-opslagplaats en open deze in Visual Studio Code.

2. Wijzig de map in de APICenter-Analyzer map in de opslagplaats.

3. In de resources/rulesets map vindt u een oas.yaml bestand. Dit bestand weerspiegelt uw huidige API-stijlhandleiding en kan worden gewijzigd op basis van de behoeften en vereisten van uw organisatie.

4. Verifieer met de Azure Developer CLI en de Azure CLI met behulp van de volgende opdrachten:

   azd auth login
   
   az login
   

5. Voer de volgende opdracht uit om de linting-infrastructuur te implementeren in uw Azure-abonnement.

   azd up
   

6. Volg de aanwijzingen om de vereiste implementatiegegevens en -instellingen op te geven, zoals de omgevingsnaam en de naam van het API-centrum. Zie Het voorbeeld uitvoeren met behulp van de Azure Developer CLI (azd) voor meer informatie.

   Notitie

   De implementatie kan enkele minuten duren.

7. Nadat de implementatie is voltooid, gaat u naar uw API-centrum in Azure Portal. Selecteer in het linkermenu gebeurtenissengebeurtenissenabonnementen> om het gebeurtenisabonnement weer te geven dat is gemaakt.

U kunt nu een API-definitiebestand uploaden naar uw API-centrum om het gebeurtenisabonnement te activeren en de linting-engine uit te voeren.

Shift-left API-governance

De meest succesvolle governance-initiatieven omvatten altijd zelf ontwikkelaars. Door traditionele principes voor shift-left toe te passen, kunnen API-platformteams ervoor zorgen dat API-producenten precies weten aan welke vereisten ze moeten voldoen om API's vroeg in de ontwikkelingscyclus te publiceren. Dit bespaart waardevolle ontwikkeltijd door de noodzaak om niet-aangrenzende API's later in de ontwikkelingscyclus te herstellen.

De API Center-extensie voor Visual Studio Code biedt API-producenten een ervaring voor het uitvoeren van API-ontwerpconformancecontroles rechtstreeks in Visual Studio Code wanneer de API wordt gebouwd. Daarnaast kunnen API-producenten de functie voor wijzigingsdetectie gebruiken om te detecteren wanneer een wijziging kan leiden tot een belangrijke chat voor API-gebruikers.

Api-ontwerpconformance in Visual Studio Code

API Center-extensie is geïntegreerd met Spectral, een JSON/YAML linter die ondersteuning biedt voor OpenAPI en aangepaste regelset. Met de extensie kunnen ontwikkelaars strikt de meegeleverde of aanbevolen API-stijlhandleiding volgen, zodat consistentie in alle API's wordt ontwikkeld in verschillende teams.

Notitie

U moet de API Center - en Spectral-extensies installeren om deze mogelijkheid te kunnen gebruiken.

Om te activeren,

1. Gebruik de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen. Type Azure API Center: Stel de actieve API-stijlgids in en druk op Enter.
2. Selecteer een van de standaardregels die zijn opgegeven, of als uw organisatie al een stijlgids heeft, gebruikt u Lokaal bestand of externe invoer-URL selecteren om de actieve regelset in Visual Studio Code op te geven. Druk op Enter.

Zodra een actieve API-stijlgids is ingesteld, activeert het openen van een OpenAPI- of AsyncAPI-specificatiebestand een lokale linting-bewerking in Visual Studio Code. Resultaten worden zowel inline weergegeven in de editor als in het venster Problemen (Problemen weergeven > of Ctrl+Shift+M).

Fouten in Visual Studio Code detecteren

Verzend-API-versies die de productiewerkstromen van consumenten verbreken, resulteert in een ontrouwbaarheid en vertrouwensverlies. Met de API Center-extensie, met behulp van optic, kunnen ontwikkelaars eenvoudig twee API-versies vergelijken en eventuele belangrijke wijzigingen detecteren die vóór de implementatie aan de API zijn geïntroduceerd.

Notitie

U moet Optic installeren om deze mogelijkheid te kunnen gebruiken. Installeer met behulp van de volgende opdracht.

*npm install -g @useoptic/optic*

Vervolgens

1. Gebruik de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen. Typ Azure API Center: Detecteer belangrijke wijziging en druk op Enter.
2. Selecteer het eerste API-specificatiedocument dat u wilt vergelijken. Geldige opties zijn API-specificaties die zijn gevonden in uw API-centrum, een lokaal bestand of de actieve editor in Visual Studio Code.
3. Selecteer het tweede API-specificatiedocument dat u wilt vergelijken. Geldige opties zijn API-specificaties die zijn gevonden in uw API-centrum, een lokaal bestand of de actieve editor in Visual Studio Code.

Visual Studio Code opent een diff-weergave tussen de twee API-specificaties. Wijzigingen die fouten veroorzaken, worden zowel inline weergegeven in de editor als in het venster Problemen (Problemen weergeven > of Ctrl+Shift+M).