API-Governance

• 5 Minuten

API-Governance wird als Praxis für die Definition und Anwendung von Standards, Richtlinien und Prozessen im großen Stil in allen Organisations-APIs definiert. API Center ermöglicht dies mit Folgendem:

• Nachverfolgen von API-Metadaten, einschließlich Titel, Beschreibung, Versionen, Definitionen und Bereitstellungen der API. Darüber hinaus können Sie Ihre eigenen benutzerdefinierten API-Metadaten (z. B. Livewebsiteinformationen, Quellcodeverwaltungs-Repository usw.) angeben, um Metadaten nachzuverfolgen, die für Ihre Organisation wichtig sind (in einem vorherigen Modul gezeigt).
• Sicherstellen, dass alle APIs so konzipiert sind, dass sie der Designphilosophie für die Organisations-API entsprechen
• Sicherstellen der zeitnahen Erkennung von API-Versionen mit Breaking Changes für nahtlose Rollouts und Kommunikation mit API-Consumern

In dieser Lerneinheit wird gezeigt, wie Sie im API Center API-Governance im großen Stil konfigurieren können.

Voraussetzungen

Um Ihre APIs mit API Center zu steuern, müssen Sie folgende Aktionen ausführen:

1. Installieren Sie die Azure CLI.
2. Installieren der Azure Developer CLI (azd).
3. Registrieren des Event Grid-Ressourcenanbieters in Ihrem Abonnement. Wenn Sie den Event Grid-Ressourcenanbieter registrieren müssen, lesen Sie Abonnieren von Ereignissen, die von einem Partner mit Azure Event Grid veröffentlicht wurden.

API-Designkonformität

API-Plattformteams sind häufig für das Definieren von Richtlinien für API-Ersteller verantwortlich. Mit API Center können Sie API-Richtlinien codieren, indem Sie Regeln mit der Open-Source-Linting-Engine Spectral definieren. Standardmäßig enthält API Center eine bereitgestellte Spectral-Regel, aber Sie können jederzeit eigene Regeln erstellen oder die große Community von Open-Source-Regelsätzen nutzen. Jedes Mal, wenn eine API-Definition hochgeladen wird, führt API Center den Spectral-Linter mit dem bereitgestellten Regelsatz aus, um die API-Definition auf Konformität mit der Regel zu überprüfen. Es wird ein Bericht zur API-Compliance generiert, den Sie in Ihrem API Center anzeigen können.

So konfigurieren Sie die API-Designkonformität für Ihre Organisation

1. Klonen Sie das GitHub-Repository und öffnen Sie es in Visual Studio Code.

2. Wechseln Sie in das Verzeichnis APICenter-Analyzer im Repository.

3. Im Ordner resources/rulesets finden Sie eine Datei oas.yaml. Diese Datei spiegelt Ihren aktuellen API-Stilleitfaden wider und kann basierend auf Ihren Organisationsanforderungen und -anforderungen geändert werden.

4. Authentifizieren Sie sich mithilfe der folgenden Befehle bei der Azure Developer CLI und der Azure-Befehlszeilenschnittstelle:

   azd auth login
   
   az login
   

5. Führen Sie den folgenden Befehl aus, um die Lintinginfrastruktur in Ihrem Azure-Abonnement bereitzustellen.

   azd up
   

6. Befolgen Sie die Anweisungen, um die erforderlichen Bereitstellungsinformationen und -einstellungen anzugeben, z. B. den Namen der Umgebung und den API Center-Namen. Ausführliche Informationen finden Sie unter Ausführen des Beispiels mithilfe der Azure Developer CLI (azd).

   Hinweis

   Die Bereitstellung kann einige Minuten dauern.

7. Navigieren Sie nach Abschluss der Bereitstellung im Azure-Portal zum API Center. Wählen Sie im linken Menü Ereignisse>Ereignisabonnementsaus, um das erstellte Ereignisabonnement anzuzeigen.

Sie können jetzt eine API-Definitionsdatei in Ihr API Center hochladen, um das Ereignisabonnement auszulösen und die Linting-Engine auszuführen.

Shift-Left-API-Governance

Zu den erfolgreichsten Governance-Initiativen gehören immer Entwickler selbst. Durch die Anwendung herkömmlicher Shift-Left-Prinzipien können API-Plattformteams sicherstellen, dass API-Ersteller genau wissen, welche Anforderungen sie erfüllen müssen, um APIs frühzeitig im Entwicklungszyklus zu veröffentlichen. Dies spart wertvolle Entwicklungszeit, da nicht konforme APIs später im Entwicklungszyklus nicht mehr korrigiert werden müssen.

Die API Center-Erweiterung für Visual Studio Code bietet API-Erstellern eine Umgebung zum Ausführen von API-Entwurfskonformitätsprüfungen direkt in Visual Studio Code, während die API erstellt wird. Darüber hinaus können API-Ersteller das Erkennungsfeature für Breaking Changes verwenden, um zu ermitteln, wann eine Änderung zu einem Breaking Change für API-Consumer führen kann.

API-Designkonformität in Visual Studio Code

Die API Center-Erweiterung ist in Spectral integriert, ein JSON-/YAML-Linter, der OpenAPI und benutzerdefinierte Regelsätze unterstützt. Die Erweiterung ermöglicht es Entwicklern, den bereitgestellten oder empfohlenen API-Styleguide strikt einzuhalten, um Konsistenz für alle APIs sicherzustellen, die in verschiedenen Teams entwickelt werden.

Aktivieren

1. Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen. Geben Sie Azure API Center: Set active API Style Guide ein, und drücken Sie die Eingabetaste.
2. Wählen Sie eine der bereitgestellten Standardregeln aus, oder verwenden Sie Lokale Datei auswählen oder Remote-URL eingeben, um den aktiven Regelsatz in Visual Studio Code anzugeben, wenn Ihre Organisation bereits einen Styleguide hat. Drücken Sie die Eingabetaste.

Sobald ein aktiver API-Styleguide festgelegt wurde, löst das Öffnen einer OpenAPI- oder AsyncAPI-basierten Spezifikationsdatei einen lokalen Lintvorgang in Visual Studio Code aus. Die Ergebnisse werden sowohl inline im Editor als auch im Fenster „Probleme“ („Anzeigen“ > „Probleme“ oder STRG+UMSCHALT+M) angezeigt.

Erkennen von Breaking Changes in Visual Studio Code

Die Bereitstellung von API-Versionen, die die Produktionsworkflows der Verbraucher unterbrechen, führt zu Unzuverlässigkeit und Vertrauensverlust. Die API Center-Erweiterung ermöglicht es Entwicklern mithilfe von Optic, zwei beliebige API-Versionen einfach zu vergleichen und vor der Bereitstellung alle Breaking Changes zu erkennen, die in der API eingeführt wurden.

Dies ergibt folgende Szenarien:

1. Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen. Geben Sie Azure API Center: Breaking Change erkennen ein, und drücken Sie die EINGABETASTE.
2. Wählen Sie das erste API-Spezifikationsdokument für den Vergleich aus. Zu den gültigen Optionen gehören API-Spezifikationen, die sich in API Center, in einer lokalen Datei oder im aktiven Editor in Visual Studio Code befinden.
3. Wählen Sie das zweite API-Spezifikationsdokument für den Vergleich aus. Zu den gültigen Optionen gehören API-Spezifikationen, die sich in API Center, in einer lokalen Datei oder im aktiven Editor in Visual Studio Code befinden.

Visual Studio Code öffnet eine Diff-Ansicht für die beiden API-Spezifikationen. Breaking Changes werden sowohl inline im Editor als auch im Fenster „Probleme“ („Anzeigen“ > „Probleme“ oder STRG+UMSCHALT+M) angezeigt.