Delen via

API's analyseren in uw API-centrum - door Microsoft beheerd

  • Artikel

Het API-centrum van uw organisatie bevat ingebouwde, door Microsoft beheerde lintingmogelijkheden (preview) voor het analyseren van API-definities voor naleving van organisatiestijlregels, waarbij zowel afzonderlijke als overzichtsrapporten worden gegenereerd. API-analyse identificeert en helpt u bij het corrigeren van veelvoorkomende fouten en inconsistenties in uw API-definities.

Met API-analyse:

  • Azure API Center analyseert automatisch uw API-definities wanneer u een API-definitie toevoegt of bijwerkt. API-definities zijn standaard voorzien van een spectrale:oas-regelset (API-stijlgids).
  • API-analyserapporten worden gegenereerd in Azure Portal, waarin wordt getoond hoe uw API-definities voldoen aan de stijlhandleiding.
  • U kunt de Azure API Center-extensie voor Visual Studio Code gebruiken om uw eigen API-stijlhandleiding lokaal aan te passen en te testen en deze vervolgens te implementeren in uw API-centrum.

Belangrijk

Als u wilt, kunt u zelfbeheerde linting en analyse inschakelen met behulp van een aangepaste Azure-functie, waarbij de ingebouwde mogelijkheden worden overschreven. Schakel een functie uit die wordt gebruikt voor zelfbeheerde linting voordat u beheerde API-analyse gebruikt.

Beperkingen

  • Momenteel worden alleen OpenAPI- en AsyncAPI-specificatiedocumenten in JSON- of YAML-indeling geanalyseerd.
  • Op dit moment configureert u één regelset en wordt deze toegepast op alle OpenAPI-definities in uw API-centrum.
  • Er zijn limieten voor het maximum aantal API-definities dat wordt geanalyseerd. Het kan enkele minuten tot 24 uur duren voordat de analyse is voltooid.

Vereisten

API-analyserapporten weergeven

Bekijk een analyseoverzicht en de analyserapporten voor uw API-definities in Azure Portal. Nadat API-definities zijn geanalyseerd, worden in de rapporten fouten, waarschuwingen en informatie weergegeven op basis van de geconfigureerde API-stijlgids.

Bekijk in het rapport API-analyse ook de regelset die is gebruikt voor de analyse en de geschiedenis van linting-pass.

Een analyseoverzicht weergeven in uw API-centrum:

  1. Navigeer in de portal naar uw API-centrum.

  2. Selecteer API-analyse in het linkermenu onder Governance. De samenvatting wordt weergegeven.

    Schermopname van het overzicht van de API-analyse in de portal.

  3. Selecteer desgewenst het pictogram api-analyserapport voor een API-definitie. Het API-analyserapport van de definitie wordt weergegeven, zoals wordt weergegeven in de volgende schermopname.

    Schermopname van een API-analyserapport in de portal.

    Tip

    U kunt het API-analyserapport ook bekijken door Analyse te selecteren in de menubalk van de API-definitie.

Regelset aanpassen

U kunt de Azure API Center-extensie voor Visual Studio Code gebruiken om de standaardregelset voor uw API-centrum aan te passen of te vervangen als de API-stijlgids van uw organisatie. U kunt bijvoorbeeld de regelset uitbreiden of aangepaste functies toevoegen.

De regelset aanpassen of vervangen:

  1. Selecteer in Visual Studio Code het pictogram Azure API Center op de activiteitenbalk.
  2. Open de .api-center-rules map in de hoofdmap van uw werkmap.
  3. Open het ruleset.yml bestand in de map voor uw API Center-resource.
  4. Wijzig of vervang de inhoud indien nodig.
  5. Sla uw wijzigingen op ruleset.ymlin .

Regelset lokaal testen

Voordat u de aangepaste regelset implementeert in uw API-centrum, valideert u deze lokaal. De Azure API Center-extensie voor Visual Studio Code biedt geïntegreerde ondersteuning voor API-specificatieplining met Spectral.

  1. Gebruik in Visual Studio Code de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen.

  2. Type Azure API Center: Stel de actieve API-stijlgids in en druk op Enter.

  3. Kies Lokaal bestand selecteren en geef het ruleset.yml bestand op dat u hebt aangepast. Druk op Enter.

    Met deze stap maakt u de aangepaste regelset de actieve API-stijlhandleiding voor linting.

Wanneer u nu een op OpenAPI gebaseerd API-definitiebestand opent, wordt er automatisch een lokale linting-bewerking geactiveerd in Visual Studio Code. Resultaten worden inline weergegeven in de editor en in het venster Problemen (Problemen weergeven > of Ctrl+Shift+M).

Tip

API-ontwikkelaars in uw organisatie kunnen deze lokale linting-mogelijkheid ook gebruiken om hun API-definities te verbeteren voordat API's in uw API-centrum worden geregistreerd.

Schermopname van het linten van een API-definitie in Visual Studio Code.

Bekijk de linting-resultaten. Breng de benodigde aanpassingen aan de regelset aan en blijf deze lokaal testen totdat deze naar wens wordt uitgevoerd.

Regelset implementeren in uw API-centrum

De aangepaste regelset implementeren in uw API-centrum:

  1. Selecteer in Visual Studio Code het pictogram Azure API Center op de activiteitenbalk.
  2. Vouw in het deelvenster API Center de API Center-resource uit waarin u de regelset hebt aangepast.
  3. Klik met de rechtermuisknop op Regels en selecteer Regels implementeren in API Center.

Er wordt een bericht weergegeven nadat de regels zijn geïmplementeerd in uw API-centrum. De linting-engine maakt gebruik van de bijgewerkte regelset om API-definities te analyseren.

Als u de resultaten van linting met de bijgewerkte regelset wilt bekijken, bekijkt u de API-analyserapporten in de portal.

Gerelateerde inhoud