Erste Schritte mit der Azure API-Center-Erweiterung für Visual Studio Code

Um APIs in Ihrem API-Center zu erstellen, zu entdecken, zu testen und zu nutzen, können Sie die Azure API-Center-Erweiterung in Ihrer Visual Studio Code-Entwicklungsumgebung verwenden:

• Erstellen von APIs – Erstellen Sie APIs und registrieren Sie sie in Ihrem API-Center, damit andere sie entdecken können. Shift-Left-API-Designkonformität überprüft Visual Studio Code mit integrierter Lintingunterstützung. Stellen Sie sicher, dass neue API-Versionen API-Consumer nicht durch die Erkennung von Breaking Changes unterbrechen.

• Entdecken von APIs – Durchsuchen Sie die APIs in Ihrem API-Center, und lesen Sie ihre Details und Dokumentation.

• Testen von APIs – Verwenden Sie die Swagger-Benutzeroberfläche oder den REST-Client, um API-Anforderungen und -Antworten zu erkunden.

• Nutzen von APIs – Generieren Sie API SDK-Clients für Ihre bevorzugte Sprache, einschließlich JavaScript, TypeScript, .NET, Python und Java, mithilfe der Microsoft Kiota-Engine, die SDKs für Microsoft Graph, GitHub und vieles mehr generiert.

Voraussetzungen

• Ein oder mehrere API-Center in Ihrem Azure-Abonnement. Wenn Sie noch keins erstellt haben, lesen Sie die Schnellstartanleitung: Erstellen Ihres API-Centers.

  Derzeit muss Ihnen die Rolle „Mitwirkender“ oder höhere Berechtigungen für den Zugriff auf API-Center mit der Erweiterung zugewiesen werden.

• Visual Studio Code

• Azure API-Center-Erweiterung für Visual Studio Code

Die folgenden Visual Studio Code-Erweiterungen sind optional und nur für bestimmte angegebene Szenarien erforderlich:

• REST-Clienterweiterung – Zum Senden von HTTP-Anforderungen und direkten Anzeigen der Antworten in Visual Studio Code
• Microsoft Kiota-Erweiterung – Zum Generieren von API-Clients
• Spektrale Erweiterung – zum Ausführen von Überprüfungen der Links-API-Designkonformität in Visual Studio Code
• Optic CLI: zur Erkennung von Breaking Changes zwischen API-Spezifikationsdokumenten
• GitHub Copilot – zum Generieren von OpenAPI-Spezifikationsdateien aus API-Code

Setup

1. Installieren Sie die Azure API-Center-Erweiterung für Visual Studio Code aus dem Visual Studio Code Marketplace. Installieren Sie bei Bedarf optionale Erweiterungen.
2. Wählen Sie in Visual Studio Code auf der Aktivitätsleiste auf der linken Seite „API-Center“ aus.
3. Wenn Sie nicht bei Ihrem Azure-Konto angemeldet sind, wählen Sie Bei Azure anmelden… aus, und folgen Sie den Anweisungen, um sich anzumelden. Wählen Sie ein Azure-Konto mit dem API-Center (oder den API-Centern) aus, von denen Sie APIs anzeigen möchten. Sie können auch nach bestimmten Abonnements filtern, wenn viele zum Anzeigen verfügbar sind.

Registrieren von APIs

Registrieren Sie eine API in Ihrem API-Center direkt über Visual Studio Code, indem Sie sie in einem einmaligen Vorgang oder mit einer CI/CD-Pipeline registrieren.

1. Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen. Geben Sie Azure API Center: Register API ein, und drücken Sie die Eingabetaste.
2. Wählen Sie aus, wie Sie Ihre API im API-Center registrieren möchten:
   • Schritt für Schritt eignet sich am besten für die einmalige Registrierung von APIs.
   • CI/CD fügt Ihrem aktiven Visual Studio Code-Arbeitsbereich eine vorkonfigurierte GitHub- oder Azure DevOps-Pipeline hinzu, die als Teil eines CI/CD-Workflows für jeden Commit zur Quellcodeverwaltung ausgeführt wird. Es wird empfohlen, APIs mit Ihrem API-Center mithilfe von CI/CD zu inventarisieren, um sicherzustellen, dass API-Metadaten, einschließlich Spezifikation und Version, im API-Center auf dem neuesten Stand bleiben, während die API im Laufe der Zeit weiterentwickelt wird.
3. Führen Sie die Registrierungsschritte aus:
   • Bei Schritt für Schritt wählen Sie das API-Center aus, bei dem Sie APIs registrieren möchten, und beantworten Sie Aufforderungen mit Informationen wie API-Titel, Typ, Lebenszyklusstufe, Version und Spezifikation, um die API-Registrierung abzuschließen.
   • Bei CI/CD wählen Sie GitHub oder Azure DevOps aus, je nachdem, welchen Mechanismus zur Quellcodeverwaltung Sie bevorzugen. Ein Visual Studio Code-Arbeitsbereich muss geöffnet sein, damit die Azure API-Center-Erweiterung Ihrem Arbeitsbereich eine Pipeline hinzufügen kann. Nachdem die Datei hinzugefügt wurde, führen Sie die Schritte aus, die in der CI/CD-Pipelinedatei selbst dokumentiert sind, um die Umgebungsvariablen und Identität der Azure-Pipeline/GitHub-Aktion zu konfigurieren. Beim Push zur Quellcodeverwaltung wird die API in Ihrem API-Center registriert.

API-Designkonformität

Um die Designkonformität mit organisatorischen Standards beim Erstellen von APIs sicherzustellen, bietet die Azure API-Center-Erweiterung für Visual Studio Code integrierte Unterstützung für das Linting der API-Spezifikation mit Spectral.

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.

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

Erkennung von Breaking Changes

Bei der Einführung neuer Versionen Ihrer API ist es wichtig, sicherzustellen, dass die eingeführten Änderungen API-Consumer in früheren Versionen Ihrer API nicht unterbrechen. Die Azure API Center-Erweiterung für Visual Studio Code erleichtert dies mit der Erkennung von Breaking Changes für OpenAPI-Spezifikationsdokumente, die von Optic unterstützt werden.

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 Vergleichsansicht der beiden API-Spezifikationen. Breaking Changes werden sowohl inline im Editor als auch im Fenster „Probleme“ angezeigt (Ansicht>Probleme oder STRG+UMSCHALT+M).

Generieren einer OpenAPI-Spezifikationsdatei aus API-Code

Verwenden Sie die Leistungsfähigkeit von GitHub Copilot mit der Azure API Center-Erweiterung für Visual Studio Code, um eine OpenAPI-Spezifikationsdatei aus Ihrem API-Code zu erstellen. Klicken Sie mit der rechten Maustaste auf den API-Code, wählen Sie Copilot aus den Optionen aus, und wählen Sie API-Dokumentation generieren aus. Dadurch wird eine OpenAPI-Spezifikationsdatei erstellt.

Nach dem Generieren der OpenAPI-Spezifikationsdatei und der Überprüfung auf Genauigkeit können Sie die API für Ihr API Center mit dem Befehl Azure API Center: API registrieren registrieren.

Ermitteln von APIs

Ihre API-Center-Ressourcen werden in der Strukturansicht auf der linken Seite angezeigt. Erweitern Sie eine API-Center-Ressource, um APIs, Versionen, Definitionen, Umgebungen und Bereitstellungen anzuzeigen.

Suchen Sie in API Center nach APIs, indem Sie das Suchsymbol verwenden, das im Strukturansichtselement APIs angezeigt wird.

Anzeigen der API-Dokumentation

Sie können die Dokumentation für eine API-Definition in Ihrem API-Center anzeigen und API-Vorgänge testen. Dieses Feature ist nur für OpenAPI-basierte APIs in Ihrem API-Center verfügbar.

1. Erweitern Sie die API-Center-Strukturansicht, um eine API-Definition anzuzeigen.

2. Klicken Sie mit der rechten Maustaste auf die Definition, und wählen Sie API-Dokumentation öffnen aus. Eine neue Registerkarte mit der Swagger-Benutzeroberfläche für die API-Definition wird angezeigt.

   

3. Um die API zu testen, wählen Sie einen Endpunkt aus, wählen Sie Ausprobieren aus, geben Sie die erforderlichen Parameter ein, und wählen Sie Ausführen aus.

   Hinweis

   Je nach API müssen Sie eventuell Anmeldeinformationen für die Autorisierung oder einen API-Schlüssel angeben, um die API zu testen.

   Tipp

   Sie können die Erweiterung auch verwenden, um API-Dokumentation in Markdown zu generieren, ein Format, das einfach verwaltet und für Endbenutzer freigegeben werden kann. Klicken Sie mit der rechten Maustaste auf die Definition, und wählen Sie Markdown generieren aus.

Generieren einer HTTP-Datei

Sie können eine .http-Datei basierend auf der API-Definition in Ihrem API-Center anzeigen. Wenn die REST-Clienterweiterung installiert ist, können Sie Anforderungen direkt über den Visual Studio Code-Editor senden. Dieses Feature ist nur für OpenAPI-basierte APIs in Ihrem API-Center verfügbar.

1. Erweitern Sie die API-Center-Strukturansicht, um eine API-Definition anzuzeigen.

2. Klicken Sie mit der rechten Maustaste auf die Definition, und wählen Sie HTTP-Datei generieren aus. Es wird eine neue Registerkarte mit einem .http-Dokument angezeigt, das von der API-Spezifikation aufgefüllt wird.

   

3. Um eine Anforderung zu senden, wählen Sie einen Endpunkt und dann Anforderung senden aus.

   Hinweis

   Je nach API müssen Sie eventuell Anmeldeinformationen für die Autorisierung oder einen API-Schlüssel angeben, um die Anforderung zu senden.

Generieren eines API-Clients

Verwenden Sie die Microsoft Kiota-Erweiterung, um einen API-Client für Ihre bevorzugte Sprache zu generieren. Dieses Feature ist nur für OpenAPI-basierte APIs in Ihrem API-Center verfügbar.

1. Erweitern Sie die API-Center-Strukturansicht, um eine API-Definition anzuzeigen.
2. Klicken Sie mit der rechten Maustaste auf die Definition, und wählen Sie API-Client generieren aus. Der Bereich Kiota OpenAPI Generator wird angezeigt.
3. Wählen Sie die API-Endpunkte und HTTP-Vorgänge aus, die Sie in Ihre SDKs aufnehmen möchten.
4. Wählen Sie API-Client generieren aus.

   1. Geben Sie Konfigurationsdetails für den SDK-Namen, den Namespace und das Ausgabeverzeichnis ein.

   2. Wählen Sie die Sprache für das generierte SDK aus.

      

Der Client wird generiert.

Details zur Verwendung der Kiota-Erweiterung finden Sie unter Microsoft Kiota-Erweiterung für Visual Studio Code.

Exportieren einer API-Spezifikation

Sie können eine API-Spezifikation aus einer Definition exportieren und dann als Datei herunterladen.

So exportieren Sie eine Spezifikation in der Strukturansicht der Erweiterung:

1. Erweitern Sie die API-Center-Strukturansicht, um eine API-Definition anzuzeigen.

2. Klicken Sie mit der rechten Maustaste auf die Definition, und wählen Sie API-Spezifikationsdokument exportieren aus. Es wird eine neue Registerkarte angezeigt, die ein API-Spezifikationsdokument rendert.

   

Sie können eine Spezifikation auch mithilfe der Befehlspalette exportieren:

1. Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen.
2. Wählen Sie Azure API Center: API-Spezifikationsdokument exportieren aus.
3. Treffen Sie eine Auswahl, um zu einer API-Definition zu navigieren. Es wird eine neue Registerkarte angezeigt, die ein API-Spezifikationsdokument rendert.

Zugehöriger Inhalt

• Azure API-Center – Wesentliche Konzepte