Wie man die API-Management-Konfiguration mit APIOps CLI verwaltet

GILT FÜR: Alle API Management-Ebenen

APIOps CLI ist ein Konfigurations-als-Code-Tool für Azure API Management. In diesem Artikel verwenden Sie es, um API-Management-Konfigurationen in lokale Artefakte zu extrahieren, die Artefakte in Git zu überprüfen, Änderungen vorzuschauen und genehmigte Artefakte in einer API-Management-Instanz zu veröffentlichen. Die CLI kann auch Gerüstdateien für GitHub Actions oder Azure Pipelines für APIOps-Workflows erstellen.

Die Schritte bieten einen minimalen Workflow, den du mit einer nicht-produktiven API-Management-Instanz überprüfen kannst. Für Architektur- und Designhinweise siehe Automatisierte API-Bereitstellungen mit APIOps.

Nutzen Sie diesen Workflow, um:

  • Überprüfen Sie API-Definitionen, Richtlinien und andere API-Management-Konfigurationen über Pull Requests.
  • Führen Sie eine prüfbare Historie genehmigter Konfigurationsänderungen.
  • Fördern Sie überprüfte Artefakte zwischen API-Management-Umgebungen.
  • Beginne mit einer Konfiguration, die aus einer bestehenden Instanz extrahiert wurde, oder erstelle CLI-kompatible Artefakte im Code.

APIOps CLI ergänzt die API-DevOps-Ansätze, die in Use DevOps and CI/CD zur Veröffentlichung von APIs beschrieben sind. Bewerten Sie die CLI und Ihren vorgesehenen Artefakt-Workflow in einer nicht-produktiven Umgebung, bevor Sie sie für Produktionsdeployments verwenden.

Voraussetzungen

  • Node.js Version 22 oder höher.
  • Azure CLI, für die lokalen Authentifizierungsschritte in diesem Artikel.
  • Ein Azure-Abonnement und eine bestehende nicht-produktive API-Management-Instanz.
  • Ein Git-Repository für deine API-Management-Artefakte.
  • Eine Identität mit Zugriff auf die API-Management-Instanz. Die Erste-Schritte-Anleitung für die APIOps-CLI führt für ihren Workflow zum Extrahieren und Veröffentlichen die Rollen API Management Service Contributor und Reader im Gültigkeitsbereich der API-Management-Ressource auf.

Für die Produktionsautomatisierung solltest du bei Möglichkeit separate, minimalprivilegierte Identitäten verwenden. Eine Extraktionsidentität benötigt Lesezugriff auf die Quellinstanz. Eine Publishing-Identität benötigt nur die Berechtigungen, die zur Aktualisierung der Zielinstanz erforderlich sind.

APIOps CLI installieren

Installieren Sie das @azure-tools/apiops-cli npm-Paket:

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

Überprüfen Sie die installierte Version:

apiops --version

Nimm die Version auf, die du für deine CI/CD-Pipelines freigibst und pinne sie. Schau dir das APIOps CLI-Changelog an, bevor du upgradest.

Authentifizieren bei Azure

Für die lokale Nutzung melden Sie sich mit der Azure CLI an und wählen Sie das Abonnement aus, das Ihre nicht-produktive API-Management-Instanz enthält:

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

APIOps CLI verwendet DefaultAzureCredential. Zusätzlich zu Azure CLI-Zugangsdaten unterstützt es auch Umgebungszugangsdaten, Arbeitslast-Identität, verwaltete Identität, Azure PowerShell und Azure Developer CLI-Zugangsdaten.

Für CI/CD verwenden Sie bevorzugt eine Workload-Identitätsföderation oder eine verwaltete Identität anstelle eines Clientgeheimnisses. Fügen Sie niemals Zugangsdaten, Zugriffstoken, Abonnementschlüssel oder geheime Nennwerte in die Quellcode-Kontrolle ein. Für unterstützte Authentifizierungsoptionen siehe den APIOps CLI-Authentifizierungsleitfaden.

Bereite ein Artefaktarchiv vor

Führen Sie APIOps-CLI-Befehle aus der Wurzel des Git-Repositoriums aus, das Ihre API-Management-Artefakte enthält.

Um Pipelines und Konfigurationsvorlagen für GitHub Actions zu erstellen, führen Sie aus:

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

Für Azure Pipelines verwenden:

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

Der Befehl erstellt Pipeline-Definitionen, eine Extraktionsfiltervorlage, Vorlagen für Umgebungsüberschreibungen, eine Anleitung zum Einrichten der Identität und ein apim-artifacts-Verzeichnis. Überprüfen Sie jede generierte Datei, bevor Sie eine Pipeline committen oder aktivieren. Verwenden Sie --force nicht in einem Repository mit vorhandenen Dateien, es sei denn, Sie überprüfen die Dateien, die der Befehl überschreibt.

Wenn Sie bereits ein Repository- und Pipeline-Design haben, können Sie stattdessen ein Artefaktverzeichnis erstellen oder auswählen und direkt die Befehle extrahieren und veröffentlichen verwenden.

Erstelle die ersten Artefakte

Wählen Sie eine der folgenden Methoden, um die Artefakte festzulegen, die Ihr Repository besitzt.

Bestehende Konfiguration extrahieren

Um eine Basislinie aus einer bestehenden API-Management-Instanz zu erstellen, extrahieren Sie deren Konfiguration:

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

Der Befehl erstellt JSON-Informationsdateien, XML-Richtliniendateien und API-Spezifikationsdateien in einer Hierarchie unter apim-artifacts. Für eine große Instanz konfigurieren Sie einen Extraktionsfilter so, dass das Repository nur die vorgesehenen Ressourcen verwaltet.

Beginnen Sie mit Code-First-Artefakten

Für einen code-first-Workflow fügen Sie eine OpenAPI-Spezifikation sowie die erforderlichen API-Management-Informationen und -Richtliniendateien mit dem APIOps-CLI-Artefaktformat hinzu. Gehen Sie nicht davon aus, dass das Layout eines bestehenden Anwendungsrepositorys oder eine OpenAPI-Datei allein für apiops publish bereit ist.

Wenn du neu im Artefaktformat bist, extrahiere zuerst eine kleine Referenz-API aus einer nicht-produktiven Instanz. Verwenden Sie die resultierenden Dateien als Vorlagen und prüfen Sie die Code-First-Workflow-Leitlinien.

Überprüfen Sie die Artefakte

Bevor Sie veröffentlichen:

  1. Überprüfen Sie die generierten oder erstellten Dateien und bestätigen Sie, dass das Repository nur die Ressourcen enthält, die Sie verwalten möchten.
  2. Überprüfen Sie API-Spezifikationen, Richtlinien, Backends, benannte Werte, Produkte und deren Abhängigkeiten.
  3. Entferne umgebungsspezifische Werte, die nicht in eine andere Umgebung verschoben werden sollten. Verwenden Sie gegebenenfalls überprüfte Umgebungsüberschreibungsdateien oder Azure Key Vault-Referenzen.
  4. Suchen Sie nach Qualifikationen und geheimen Werten. Bei der Extraktion werden unterstützte vertrauliche Felder und erkannte Richtlinienmuster geschwärzt, jedoch wird möglicherweise nicht jedes eingebettete Geheimnis erkannt. Hinterlasse keine Geheimnisse oder ungelöste *** REDACTED *** Werte.
  5. Verbinde die Artefakte mit einem Branch und nutze einen Pull Request zur Validierung und Genehmigung.

Vorschau einer Veröffentlichung

Führe einen Probelauf gegen die Nicht-Produktionszielinstanz durch. Ein Probelauf meldet geplante Erstellungen, Aktualisierungen und Löschungen, ohne sie auszuführen:

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

Überprüfen Sie die Ausgabe und beheben Sie unerwartete Änderungen oder fehlende Abhängigkeiten. Ein erfolgreicher Trockenlauf ersetzt nicht das Testen von API-Verhalten, Richtlinien, Berechtigungen oder Backend-Konnektivität.

Caution

Füge --delete-unmatched nicht zu deinem ersten Workflow hinzu. Diese Option löscht Ressourcen in der Zielinstanz, die in den Quellartefakten nicht dargestellt sind.

Veröffentlichen Sie die überprüften Artefakte

Nachdem der Pull Request genehmigt wurde und der Problelauf erfolgreich war, veröffentlichen Sie dieselben überprüften Artefakte im Nicht-Produktionsziel:

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

Validiere die APIs und Richtlinien in der Zielinstanz nach der Veröffentlichung. Wenn Sie diesen Workflow automatisieren, konfigurieren Sie die Pipeline so, dass sie einen genehmigten Commit veröffentlicht und Deployment-Umgebungen mit den erforderlichen Prüfungen und Genehmigungen Ihrer Organisation schützt.

Nächste Schritte

  • Zuletzt aktualisiert um