Aktivieren und Anzeigen des Azure API Center-Plattform-API-Katalogs

In diesem Artikel wird gezeigt, wie Sie für die Entwicklung in Unternehmen zuständigen Personen Zugriff auf den Azure API Center-Plattform-API-Katalog (Preview) in der Visual Studio Code-Erweiterung für Azure API Center gewähren. Mithilfe des Plattform-API-Katalogs können Entwickelnde APIs in Ihrem Azure-API-Center entdecken, API-Definitionen anzeigen und optional API-Clients generieren, wenn sie keinen Zugriff auf die Verwaltung des API-Centers selbst haben oder APIs zum Inventar hinzufügen können. Der Zugriff auf den Plattform-API-Katalog wird mithilfe von Microsoft Entra ID und der rollenbasierten Zugriffssteuerung von Azure verwaltet.

Voraussetzungen

Für API Center-Admins

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

• Berechtigungen zum Erstellen einer App-Registrierung in einem Microsoft Entra-Mandanten, der Ihrem Abonnement zugeordnet ist, und Berechtigungen zum Gewähren des Zugriffs auf Daten in Ihrem API Center.

Für App-Entwickelnde

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

  Wichtig

  Der Zugriff auf den Plattform-API-Katalog ist derzeit nur in der Vorabversion der Erweiterung verfügbar. Wenn Sie die Erweiterung aus dem Visual Studio Code Marketplace installieren, können Sie die endgültige Produktversion oder eine Vorabversion installieren. Wechseln Sie jederzeit zwischen den beiden Versionen, indem Sie das Kontextmenü der Erweiterungsschaltfläche Verwalten in der Erweiterungsansicht verwenden.

Die folgende Visual Studio Code-Erweiterung ist optional:

• Microsoft Kiota-Erweiterung – Zum Generieren von API-Clients

Schritte für API Center-Admins zum Aktivieren des Zugriffs auf den Katalog

Die folgenden Abschnitte enthalten Schritte für API Center-Admins, um Personen im Unternehmen, die für die Entwicklung zuständig sind, den Zugriff auf den Plattform-API-Katalog zu ermöglichen.

Erstellen einer Microsoft Entra-App-Registrierung

Konfigurieren Sie zunächst eine App-Registrierung in Ihrem Microsoft Entra ID-Mandanten. Die App-Registrierung ermöglicht der Visual Studio Code-Erweiterung für Azure API Center den Zugriff auf den Plattform-API-Katalog im Namen von angemeldeten Benutzenden.

1. Navigieren Sie im Azure-Portal zu Microsoft Entra ID>App-Registrierungen.

2. Wählen Sie + Neue Registrierung aus.

3. Legen Sie auf der Seite Anwendung registrieren die Werte wie folgt fest:

   • Legen Sie Name auf einen aussagekräftigen Namen wie plattform-api-catalog fest.
   • Wählen Sie unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis (Einzelmandant) aus.
   • Wählen Sie unter Umleitungs-URI die Option Single-Page-Webanwendung (SPA) aus, und legen Sie den URI auf den Runtime-URI Ihres API-Centers fest. Beispiel: https://<service name>.data.<region>.azure-apicenter.ms. Beispiel: https://contoso-apic.data.eastus.azure-apicenter.ms.
   • Wählen Sie Registrieren aus.

   Tipp

   Sie können dieselbe App-Registrierung für den Zugriff auf weitere API-Center verwenden. Fügen Sie in Umleitungs-URI außerdem Umleitungs-URIs für andere API-Center hinzu, die im Plattform-API-Katalog angezeigt werden sollen.

4. Kopieren Sie auf der Seite Übersicht die Werte für Anwendungs-ID (Client) und Verzeichnis-ID (Mandant). Sie legen diese Werte später fest, wenn Sie über die Visual Studio Code-Erweiterung eine Verbindung mit dem API Center herstellen.

5. Wählen Sie im linken Menü unter Verwalten die Optionen Authentifizierung>+ Plattform hinzufügen aus.

6. Wählen Sie auf der Seite Plattformen konfigurieren Mobile- und Desktopanwendungen aus.

7. Geben Sie auf der Seite Konfigurieren von Desktop und Geräten den folgenden Umleitungs-URI ein, und wählen Sie Konfigurieren aus:

   https://vscode.dev/redirect

8. Wählen Sie im Menü auf der linken Seite unter Verwalten die Option API-Berechtigungen>+ Berechtigung hinzufügen aus.

9. Gehen Sie auf der Seite API-Berechtigungen anfordern wie folgt vor:

   1. Wählen Sie die Registerkarte Von meiner Organisation verwendete APIs aus.
   2. Suchen Sie nach Azure API Center, und wählen Sie diesen Eintrag aus. Sie können auch nach der Anwendungs-ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573 suchen und diese auswählen.
   3. Wählen Sie auf der Seite Berechtigungen auswählen die Option user_impersonation aus.
   4. Wählen Sie Zugriffsrechte hinzufügen.

   Die Berechtigungen für Azure API Center werden unter Konfigurierte Berechtigungen angezeigt.

   

Aktivieren der Anmeldung von Microsoft Entra-Benutzern oder-Gruppen beim Plattform-API-Katalog

Sie müssen sich mit einem Microsoft-Konto anmelden, um den Plattform-API-Katalog für Ihr API Center anzuzeigen. Falls erforderlich, müssen Sie Entwickelnde zu Ihrem Microsoft Entra-Mandanten hinzufügen oder einladen.

Um die Anmeldung dann zu aktivieren, weisen Sie Benutzenden oder Gruppen in Ihrem Mandanten die Rolle Azure API Center-Datenlesende zu, die Ihrem API Center zugeordnet sind.

Ausführliche Informationen zu den Voraussetzungen und die Schritte zum Zuweisen einer Rolle zu Benutzern und Gruppen finden Sie unter Zuweisen von Azure-Rollen über das Azure-Portal. Im Folgenden sind die erforderlichen Schritte kurz zusammengefasst:

1. Navigieren Sie im Azure-Portal zu Ihrem API Center.
2. Wählen Sie im Menü auf der linken Seite Zugriffssteuerung (IAM)>Rollenzuweisung hinzufügen aus.
3. Legen Sie im Bereich Rollenzuweisung hinzufügen die Werte wie folgt fest:
   • Suchen Sie auf der Seite Rolle nach Azure API Center-Datenleser, und wählen Sie den Eintrag aus. Wählen Sie Weiter aus.
   • Wählen Sie auf der Seite Mitglieder unter Zugriff zuweisen zu die Optionen Benutzer, Gruppe oder Dienstprinzipal>Mitglieder auswählen aus.
   • Suchen Sie auf der Seite Mitglieder auswählen nach den Benutzern oder Gruppen, denen Sie die Rolle zuweisen möchten, und wählen Sie sie aus. Wählen Sie Auswählen und dann Weiter aus.
   • Überprüfen Sie die Rollenzuweisung, und wählen Sie Überprüfen + zuweisen aus.
4. Wiederholen Sie die vorherigen Schritte, um die Anmeldung beim Plattform-API-Katalog für weitere API-Center zu aktivieren.

Schritte für Unternehmensentwicklende für den Zugriff auf den Plattform-API-Katalog

Entwickelnde können diese Schritte ausführen, um mithilfe der Visual Studio Code-Erweiterung eine Verbindung herzustellen und sich anzumelden, um einen Plattform-API-Katalog anzuzeigen. Die Einstellungen zum Herstellen einer Verbindung mit dem API Center müssen von den Verantwortlichen für die Administration des API-Center bereitgestellt werden.

Herstellen einer Verbindung mit einem API-Center

1. Installieren Sie die Vorabversion der Azure API-Center-Erweiterung für Visual Studio Code für Visual Studio Code.

2. Wählen Sie in Visual Studio Code auf der Aktivitätsleiste auf der linken Seite „API-Center“ aus.

   

3. Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen. Geben Sie Azure API-Center: Verbindung mit einem API Center herstellen ein, und drücken Sie die Eingabetaste ein.

4. Beantworten Sie die Aufforderungen mit den folgenden Informationen:

   1. Die Runtime-URL Ihres API-Centers im Format <service name>.data.<region>.azure-apicenter.ms (ohne das Präfix https://). Beispiel: contoso-apic.data.eastus.azure-apicenter.ms. Diese Runtime-URL wird auf der Übersichtsseite des API-Centers im Azure-Portal angezeigt.
   2. Die Anwendungs-ID (Client-ID) aus der App-Registrierung, die im vorherigen Abschnitt durch eine Person mit Adminrechten konfiguriert wurde.
   3. Die Verzeichnis-ID (Mandanten-ID) aus der App-Registrierung, die im vorherigen Abschnitt durch eine Person mit Adminrechten konfiguriert wurde.

   Tipp

   Diese Verbindungsdetails erhalten Sie von einer Person mit Adminrechten für das API-Center oder über einen direkten Link im folgenden Format:
   vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

   Nachdem Sie eine Verbindung mit dem API-Center hergestellt haben, wird der Name des API-Centers im Plattform-API-Katalog des API-Centers angezeigt.

5. Um die APIs im API-Center anzuzeigen, wählen Sie unter dem Namen des API-Centers Bei Azure anmelden aus. Die Anmeldung können alle Personen mit einem Microsoft-Konto durchführen, dem im API-Center die Rolle Azure API Center-Datenlesende zugewiesen ist.

   

6. Wählen Sie nach der Anmeldung APIs aus, um die APIs im API Center auflisten zu können. Erweitern Sie eine API, um ihre Versionen und Definitionen zu erkunden.

   

7. Wiederholen Sie die vorstehenden Schritte, um eine Verbindung mit weiteren API-Centern herzustellen, wenn der Zugriff konfiguriert ist.

Entdecken und Nutzen von APIs im Katalog

Der Plattform-API-Katalog hilft Entwickelnden im Unternehmen, API-Details zu ermitteln und die API-Cliententwicklung zu starten. Das Entwicklungsteam kann durch Rechtsklick auf eine API-Definition im Plattform-API-Katalog auf die folgenden Features zugreifen:

• Export von API-Spezifikationsdokumenten – Exportieren einer API-Spezifikation aus einer Definition und anschließendes Herunterladen als Datei
• Generieren eines API-Client – Verwenden der Microsoft Kiota-Erweiterung, um einen API-Client für die bevorzugte Sprache zu generieren
• Generieren von Markdown – Generieren einer API-Dokumentation im Markdown-Format
• OpenAPI-Dokumentation – Anzeigen der Dokumentation für eine API-Definition, und Ausprobieren von Vorgängen in einer Swagger-Benutzeroberfläche (nur für OpenAPI-Definitionen verfügbar)

Problembehandlung

Fehler: Eigenschaften von Undefined können nicht gelesen werden (Lesen von „nextLink“)

Unter bestimmten Umständen kann nach dem Einloggen beim Plattform-API-Katalog des API-Centers und Erweitern der API-Liste für ein API-Center die folgende Fehlermeldung angezeigt werden:

Error: Cannot read properties of undefined (reading 'nextLink')

Vergewissern Sie sich, dass dem betreffenden Benutzerkonto in Ihrem API-Center die Rolle Azure API Center-Datenlesende zugewiesen ist. Weisen Sie dem Benutzerkonto die Rolle wenn nötig zu. Aktualisieren Sie dann den Plattform-API-Katalog des API-Centers in der Visual Studio Code-Erweiterung.

Anmeldung bei Azure nicht möglich

Wenn Benutzende, denen die Rolle Azure API Center-Datenlesende zugewiesen wurde, den Anmeldevorgang nicht abschließen können, nachdem sie im Plattform-API-Katalog die Option Bei Azure anmelden gewählt haben, liegt möglicherweise ein Problem mit der Verbindungskonfiguration vor.

Überprüfen Sie die Einstellungen in der App-Registrierung, die Sie in Microsoft Entra ID konfiguriert haben. Bestätigen Sie die Werte der Anwendungs-ID (Client-ID) und der Verzeichnis-ID (Mandanten-ID) in der App-Registrierung und der Runtime-URL des API-Centers. Richten Sie dann die Verbindung zum API-Center erneut ein.

Auswahl von Azure API-Center-Berechtigungen in der Microsoft Entra ID-App-Registrierung nicht möglich

Vergewissern Sie sich, dass Sie nach Azure API Center (oder der Anwendungs-ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573) suchen, wenn Sie in Ihrer Microsoft Entra-App-Registrierung für das API Center-Portal keine API-Berechtigungen für Azure API Center anfordern können.

Wenn die App nicht vorhanden ist, liegt möglicherweise ein Problem mit der Registrierung des Ressourcenanbieters Microsoft.ApiCenter in Ihrem Abonnement vor. In diesem Fall müssen Sie den Ressourcenanbieter möglicherweise erneut registrieren. Führen Sie dazu den folgenden Befehl in der Azure-Befehlszeilenschnittstelle (Azure Command Line Interface, Azure CLI) aus:

az provider register --namespace Microsoft.ApiCenter

Versuchen Sie nach der erneuten Registrierung des Ressourcenanbieters nochmals, die API-Berechtigungen anzufordern.

Zugehöriger Inhalt

• Erstellen und Registrieren von APIs mit der Azure API-Center-Erweiterung für Visual Studio Code
• Bewährte Methoden für Azure RBAC
• Registrieren eines Ressourcenanbieters