Hoe je API-beheerconfiguratie met APIOps CLI beheert

Van toepassing op: Alle API Management-lagen

APIOps CLI is een configuratie-als-code tool voor Azure API Management. In dit artikel gebruik je het om API-beheerconfiguraties te extraheren in lokale artefacten, de artefacten in Git te bekijken, wijzigingen te bekijken en goedgekeurde artefacten te publiceren in een API Management-instantie. De CLI kan ook GitHub Actions- of Azure-pipelines-bestanden genereren voor een APIOps-workflow.

De stappen bieden een minimale workflow die je kunt valideren met een niet-productieve API Management-instantie. Voor architectuur- en ontwerprichtlijnen, zie Geautomatiseerde API-implementaties met APIOps.

Gebruik deze workflow om:

  • Bekijk API-definities, beleidsregels en andere API-beheerconfiguraties via pull requests.
  • Houd een controleerbare geschiedenis bij van goedgekeurde configuratiewijzigingen.
  • Promoveer beoordeelde artefacten tussen API-beheeromgevingen.
  • Begin met configuratie die is geëxtraheerd uit een bestaande instantie of auteur CLI-compatibele artefacten in code.

APIOps CLI vult de API DevOps-benaderingen aan die zijn beschreven in Use DevOps and CI/CD om API's te publiceren. Evalueer de CLI en je bedoelde artefactworkflow in een niet-productieomgeving voordat je het gebruikt voor productie-implementaties.

Prerequisites

  • Node.js versie 22 of hoger.
  • Azure CLI, voor de lokale authenticatiestappen in dit artikel.
  • Een Azure-abonnement en een bestaande niet-productieve API Management-instantie.
  • Een Git-repository voor je API-beheerartefacten.
  • Een identiteit met toegang tot de API Management-instantie. De APIOps CLI-handleiding voor aan de slag vermeldt de rollen API Management Service Contributor en Reader binnen het bereik van de API Management-resource voor de werkstroom voor extraheren en publiceren.

Gebruik voor productieautomatisering aparte, minst privilege identiteiten waar mogelijk. Een extractie-identiteit heeft leestoegang nodig tot de broninstantie. Een publicatie-identiteit heeft alleen de benodigde rechten nodig om de doelinstantie bij te werken.

APIOps CLI installeren

Installeer het @azure-tools/apiops-cli npm-pakket:

npm install -g @azure-tools/apiops-cli

Controleer de geïnstalleerde versie:

apiops --version

Leg de versie die je hebt goedgekeurd vast en zet die vast voor je CI/CD-pipelines. Bekijk de APIOps CLI-wijzigingslijst voordat je upgradet.

Verifiëren bij Azure

Voor lokaal gebruik log je in met Azure CLI en selecteer je het abonnement dat je niet-productieve API Management-instantie bevat:

az login
az account set --subscription <subscription-id>

APIOps CLI gebruikt DefaultAzureCredential. Naast Azure CLI-credentials ondersteunt het omgevingscredentials, workload-identiteit, managed identity, Azure PowerShell en Azure Developer CLI-credentials.

Voor CI/CD geef je de voorkeur aan workload identity federation of managed identity in plaats van een client secret. Sla inloggegevens, toegangstokens, abonnementssleutels of geheime waarden met een naam nooit op in broncodebeheer. Voor ondersteunde authenticatieopties, zie de APIOps CLI-authenticatiehandleiding.

Bereid een artefactenrepository voor

Voer APIOps CLI-commando's uit vanaf de root van de Git-repository die je API Management-artefacten bevat.

Om pijplijnen en configuratiesablonen voor GitHub Actions te genereren, voer je uit:

apiops init --ci github-actions --environments dev,prod --non-interactive

Voor Azure-pipelines, gebruik:

apiops init --ci azure-devops --environments dev,prod --non-interactive

Het commando maakt pijplijndefinities, een extractiefiltertemplate, omgevingsoverride-sjablonen, richtlijnen voor identiteitsopstelling en een apim-artifacts directory. Bekijk elk gegenereerd bestand voordat je een pipeline committeert of activeert. Gebruik het niet --force in een repository met bestaande bestanden tenzij je de bestanden bekijkt die het commando overschrijft.

Als je al een repository- en pipeline-ontwerp hebt, kun je in plaats daarvan een artefactmap aanmaken of selecteren en direct de extract- en publiceercommando's gebruiken.

Maak de eerste artefacten

Kies een van de volgende methoden om de artefacten vast te stellen die je repository bezit.

Haal bestaande configuratie eruit

Om een basislijn te creëren uit een bestaande API Management-instantie, haalt u de configuratie ervan uit:

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

Het commando maakt JSON-informatiebestanden, XML-beleidsbestanden en API-specificatiebestanden aan in een hiërarchie onder apim-artifacts. Voor een grote instantie configureer je een extractiefilter zodat de repository alleen de bedoelde resources beheert.

Start met code-first-artefacten

Voor een code-first workflow voeg je een OpenAPI-specificatie toe en de vereiste API-beheerinformatie en beleidsbestanden door gebruik te maken van het APIOps CLI-artefactformaat. Ga er niet van uit dat een bestaande applicatierepository-lay-out of een OpenAPI-bestand op zichzelf al klaar is voor apiops publish.

Als je nieuw bent met het artefactformaat, haal dan eerst een kleine referentie-API uit een niet-productie-instantie. Gebruik de resulterende bestanden als sjablonen en bekijk de code-first workflowrichtlijnen.

Bekijk de artefacten

Voordat je publiceert:

  1. Controleer de gegenereerde of geauthoriseerde bestanden en bevestig dat de repository alleen de resources bevat die je wilt beheren.
  2. Bekijk API-specificaties, beleid, backends, benoemde waarden, producten en hun afhankelijkheden.
  3. Verwijder omgevingsspecifieke waarden die niet naar een andere omgeving zouden moeten verplaatsen. Gebruik indien van toepassing gecontroleerde omgevingsoverschrijvingsbestanden of Azure Key Vault-referenties.
  4. Zoek naar inloggegevens en geheime waarden. Extraction redigeert ondersteunde geheime velden en herkende beleidspatronen, maar detecteert mogelijk niet elk ingesloten geheim. Verbind geen geheimen of onopgeloste *** REDACTED *** waarden.
  5. Voer de artefacten door naar een branch en gebruik een pull request om ze te valideren en goed te keuren.

Bekijk een publicatie

Doe een proefrun met de niet-productiegerichte doelinstantie. Een testuitvoering toont geplande creaties, wijzigingen en verwijderingen zonder deze uit te voeren:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

Bekijk de output en los onverwachte veranderingen of ontbrekende afhankelijkheden op. Een succesvolle proefrun vervangt het testen van API-gedrag, beleid, permissies of backend-connectiviteit niet.

Caution

Voeg --delete-unmatched niet toe aan je eerste workflow. Die optie verwijdert resources in de doelinstantie die niet in de bronartefacten worden weergegeven.

Publiceer de beoordeelde artefacten

Nadat de pull-aanvraag is goedgekeurd en de testuitvoering succesvol is verlopen, publiceer je dezelfde beoordeelde artefacten naar de niet-productiedoelomgeving:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

Valideer de API's en beleidsregels in de doelinstantie na publicatie. Wanneer je deze workflow automatiseert, configureer je de pipeline om een goedgekeurde commit te publiceren en de deployment-omgevingen te beschermen met de vereiste controles en goedkeuringen van je organisatie.

Volgende stappen 

  • Laatst bijgewerkt om