Hur man hanterar API-hanteringskonfiguration med APIOps CLI

GÄLLER FÖR: Alla API Management-nivåer

APIOps CLI är ett konfigurations-som-kod-verktyg för Azure API Management. I den här artikeln använder du den för att extrahera API-hanteringskonfiguration till lokala artefakter, granska artefakterna i Git, förhandsgranska ändringar och publicera godkända artefakter till en API Management-instans. CLI:n kan också stödja GitHub Actions eller Azure-pipelines-filer för ett APIOps-arbetsflöde.

Stegen ger ett minimalt arbetsflöde som du kan validera med en icke-produktions API Management-instans. För arkitektur- och designguider, se Automatiserade API-utrullningar med APIOps.

Använd detta arbetsflöde för att:

  • Gå igenom API-definitioner, policyer och annan API-hanteringskonfiguration via pull requests.
  • För en granskabar historik över godkända konfigurationsändringar.
  • Främja granskade artefakter mellan API-hanteringsmiljöer.
  • Börja med konfiguration extraherad från en befintlig instans eller skapa CLI-kompatibla artefakter i koden.

APIOps CLI kompletterar API:s DevOps-metoder som beskrivs i Use DevOps and CI/CD to publish APIs. Utvärdera CLI:n och ditt avsedda artefaktarbetsflöde i en icke-produktionsmiljö innan du använder det för produktionsdistributioner.

Förutsättningar

  • Node.js version 22 eller senare.
  • Azure CLI, för de lokala autentiseringsstegen i denna artikel.
  • Ett Azure-abonnemang och en befintlig icke-produktions API Management-instans.
  • Ett Git-arkiv för dina API-hanteringsartefakter.
  • En identitet med åtkomst till API-hanteringsinstansen. APIOps CLI-guiden för att komma igång listar API-hanteringstjänstens bidrags- och läsarroller i API-hanteringsresursomfängden för dess extrakt- och publiceringsarbetsflöde.

För produktionsautomation, använd separata, minst privilegierade identiteter när det är möjligt. En extraktionsidentitet behöver läsåtkomst till källinstansen. En publiceringsidentitet behöver endast de behörigheter som krävs för att uppdatera målinstansen.

Installera APIOps CLI

@azure-tools/apiops-cli Installera npm-paketet:

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

Kontrollera den installerade versionen:

apiops --version

Registrera och fäst den version som du godkänner för dina CI/CD-pipelines. Gå igenom APIOps CLI-ändringsloggen innan du uppgraderar.

Autentisera till Azure

För lokal användning, logga in med Azure CLI och välj prenumerationen som innehåller din icke-produktions API Management-instans:

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

APIOps CLI använder DefaultAzureCredential. Utöver Azure CLI-uppgifter stöder den miljöuppgifter, arbetsbelastningsidentitet, hanterad identitet, Azure PowerShell och Azure Developer CLI-uppgifter.

Vid CI/CD använder du hellre arbetsbelastningsidentitetsfederation eller hanterad identitet istället för en klienthemlighet. Lägg aldrig in inloggningsuppgifter, åtkomsttokens, prenumerationsnycklar eller hemliga namngivna värden i versionshanteringen. För stödda autentiseringsalternativ, se APIOps CLI-autentiseringsguide.

Förbered ett artefaktarkiv

Kör APIOps CLI-kommandon från roten i Git-arkivet som innehåller dina API Management-artefakter.

För att skapa pipelines och konfigurationsmallar för GitHub Actions, kör:

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

För Azure-pipelines, använd:

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

Kommandot skapar pipeline-definitioner, en extraktionsfiltermall, miljööverskrivningsmallar, identitetsinställning och en apim-artifacts katalog. Granska varje genererad fil innan du committar eller aktiverar en pipeline. Använd inte --force i ett repository med befintliga filer om du inte granskar filerna som kommandot skriver över.

Om du redan har en repository- och pipelinedesign kan du istället skapa eller välja en artefaktkatalog och använda extrahera- och publiceringskommandona direkt.

Skapa de initiala artefakterna

Välj ett av följande metoder för att fastställa de artefakter som ditt arkiv äger.

Extrahera befintlig konfiguration

För att skapa en baslinje från en befintlig API-hanteringsinstans, extrahera dess konfiguration:

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

Kommandot skapar JSON-informationsfiler, XML-policyfiler och API-specifikationsfiler i en hierarki under apim-artifacts. För en stor instans, konfigurera ett extraktionsfilter så att arkivet endast hanterar de avsedda resurserna.

Börja med artefakter med kod som utgångspunkt

För ett kodförst-arbetsflöde, lägg till en OpenAPI-specifikation och de nödvändiga API-hanterings- och policyfilerna genom att använda APIOps CLI-artefaktformat. Anta inte att en befintlig applikationsarkivlayout eller en OpenAPI-fil i sig är redo för apiops publish.

Om du är ny på artefaktformatet, extrahera först ett litet referens-API från en icke-produktionsinstans. Använd de resulterande filerna som mallar och granska kod-först-arbetsflödesguiden.

Granska artefakterna

Innan du publicerar:

  1. Granska de genererade eller författade filerna och bekräfta att arkivet endast innehåller de resurser du tänker hantera.
  2. Gå igenom API-specifikationer, policyer, backends, namngivna värden, produkter och deras beroenden.
  3. Ta bort miljöspecifika värden som inte borde flyttas till en annan miljö. Använd granskade miljööverskrivningsfiler eller Azure Key Vault-referenser där det är lämpligt.
  4. Sök efter legitimation och hemliga värden. Extraktionsredigeringar stödde hemliga fält och igenkände policymönster, men den kanske inte upptäckte varje inbäddad hemlighet. Avslöja inga hemligheter eller olösta *** REDACTED *** värderingar.
  5. Commita artefakterna till en branch och använd en pull request för validering och godkännande.

Förhandsgranska en publicering

Kör en testkörning mot målinstansen som inte är i produktion. En torrkörning rapporterar planerade skapanden, uppdateringar och raderingar utan att tillämpa dem:

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

Gå igenom resultatet och åtgärda oväntade förändringar eller saknade beroenden. En lyckad testkörning ersätter inte testning av API-beteende, policyer, behörigheter eller backend-anslutning.

Caution

Lägg inte till --delete-unmatched i ditt första arbetsflöde. Det alternativet tar bort resurser i målinstansen som inte representeras i källartefakten.

Publicera de granskade artefakterna

Efter att pull request har godkänts och testkörningen lyckats, publicera samma granskade artefakter till icke-produktionsmålet:

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

Validera API:erna och policyerna i målinstansen efter publicering. När du automatiserar detta arbetsflöde, konfigurera pipelinen för att publicera en godkänd commit och skydda distributionsmiljöer med organisationens nödvändiga kontroller och godkännanden.

Nästa steg

  • Last updated on