Freigeben über

Selbsthosten des API Center-Portals

  • Artikel

In diesem Artikel wird das API Center-Portal vorgestellt. Dabei handelt es sich um eine Website, die Entwickler und andere Projektbeteiligte in Ihrer Organisation verwenden können, um die APIs in Ihrer API Center-Instanz zu ermitteln. Stellen Sie eine Referenzimplementierung des Portals über das Startrepository für das API Center-Portal bereit.

Screenshot des API Center-Portals nach der Benutzeranmeldung.

Informationen zum API Center-Portal

Das API Center-Portal ist eine Website, die Sie erstellen und hosten können, um den API-Bestand in API Center anzuzeigen. Mit dem Portal können Entwickler und andere Projektbeteiligte in Ihrer Organisation APIs ermitteln und API-Details anzeigen.

Sie können eine Referenzimplementierung des Portals mithilfe von Code über das Startrepository für das API Center-Portal bereitstellen. Das Portal verwendet die Azure API Center-Datenebenen-API, um Daten aus Ihrer API Center-Instanz abzurufen. Der Benutzerzugriff auf API-Informationen basiert auf der rollenbasierten Zugriffssteuerung in Azure.

Die Referenzimplementierung des API Center-Portals bietet Folgendes:

  • Ein Framework zum Veröffentlichen und Verwalten eines kundenseitig verwalteten API-Portals mithilfe von GitHub Actions
  • Eine Portalplattform, die Kunden entsprechend ihren Anforderungen ändern oder erweitern können
  • Flexibilität beim Hosten in verschiedenen Infrastrukturen, einschließlich Bereitstellung für Dienste wie Azure Static Web Apps

Voraussetzungen

  • 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.

  • Zum Erstellen und Bereitstellen des Portals benötigen Sie ein GitHub-Konto. Außerdem müssen die folgenden Tools auf Ihrem lokalen Computer installiert sein:

Erstellen einer Microsoft Entra-App-Registrierung

Konfigurieren Sie zunächst eine App-Registrierung in Ihrem Microsoft Entra ID-Mandanten. Die App-Registrierung ermöglicht es dem API Center-Portal, im Namen eines angemeldeten Benutzers auf Daten aus Ihrem API Center zuzugreifen.

  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 api-center-portal 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 fest.

      • Legen Sie für lokale Tests den URI auf https://localhost:5173 fest.
      • Legen Sie für die Produktion den URI auf den URI der API Center-Portalbereitstellung fest.

    • Wählen Sie Registrieren aus.

  4. Kopieren Sie auf der Seite Übersicht die Werte für Anwendungs-ID (Client) und Verzeichnis-ID (Mandant). Sie legen diese Werte beim Erstellen des Portals fest.

  5. Wählen Sie auf der Seite API-Berechtigungen die Option Berechtigung hinzufügen aus.

    1. Wählen Sie auf der Seite API-Berechtigungen anfordern die Registerkarte Von meiner Organisation verwendete APIs aus. 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.
    2. Wählen Sie auf der Seite Berechtigungen anfordern die Option user_impersonation aus.
    3. Wählen Sie Zugriffsrechte hinzufügen.

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

    Screenshot der erforderlichen Berechtigungen in der Microsoft Entra ID-App-Registrierung im Portal.

Konfigurieren der lokalen Umgebung

Führen Sie die folgenden Schritte aus, um das API Center-Portal lokal zu erstellen und zu testen.

  1. Klonen Sie das Startrepository für das API Center-Portal auf Ihrem lokalen Computer.

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. Wechseln Sie in das Verzeichnis APICenter-Portal-Starter.

    cd APICenter-Portal-Starter

  3. Checken Sie den Mainbranch aus.

    git checkout main

  4. Um den Dienst zu konfigurieren, kopieren Sie die public/config.example-Datei oder benennen Sie sie in public/config.json um.

  5. Bearbeiten Sie dann die public/config.json-Datei, um auf Ihren Dienst zu verweisen. Aktualisieren Sie die Werte in der Datei wie folgt:

    • Ersetzen Sie <service name> und <region> durch den Namen Ihrer API Center-Instanz und die Region, in der sie bereitgestellt wird.
    • Ersetzen Sie <client ID> und <tenant ID> durch die Werte für Anwendungs-ID (Client) und Verzeichnis-ID (Mandant) der App-Registrierung, die Sie im vorherigen Abschnitt erstellt haben.
    • Aktualisieren Sie den Wert von title auf einen Namen, der im Portal angezeigt werden soll.
    {
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. Installieren erforderlicher Pakete

    npm install

  7. Starten Sie den Entwicklungsserver. Mit dem folgenden Befehl wird das Portal im Entwicklungsmodus gestartet und lokal ausgeführt:

    npm start

    Navigieren Sie zum Portal unter https://localhost:5173.

Bereitstellung in Azure

Schritte zum Bereitstellen des Portals in Azure Static Web Apps finden Sie im Startrepository für das API Center-Portal.

Aktivieren der Anmeldung von Microsoft Entra-Benutzern oder-Gruppen beim Portal

Benutzer müssen sich anmelden, um die APIs in Ihrer API Center-Instanz anzuzeigen. Um die Anmeldung zu aktivieren, weisen Sie die Rolle Azure API Center-Datenleser Benutzern oder Gruppen in Ihrer Organisation zu, die Ihrem API Center zugeordnet sind.

Wichtig

Standardmäßig haben Sie und andere Administratoren des API Center keinen Zugriff auf APIs im API Center-Portal. Sie müssen die Rolle Azure API Center-Datenleser sich selbst und anderen Administratoren zuweisen.

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.

Hinweis

Um die Zugriffskonfiguration für neue Benutzer zu optimieren, empfiehlt es sich, die Rolle einer Microsoft Entra-Gruppe zuzuweisen und eine Regel für dynamische Gruppenmitgliedschaft zu konfigurieren. Weitere Informationen finden Sie unter Erstellen oder Aktualisieren einer dynamischen Gruppe in Microsoft Entra ID.

Nachdem Sie den Zugriff auf das Portal konfiguriert haben, können sich konfigurierte Benutzer beim Portal anmelden und die APIs in Ihrem API Center anzeigen.

Hinweis

Der erste Benutzer, der sich beim Portal anmeldet, wird aufgefordert, den Berechtigungen zuzustimmen, die von der App-Registrierung für das API Center-Portal angefordert werden. Andere konfigurierte Benutzer werden danach nicht mehr aufgefordert, ihre Einwilligung zu erteilen.

Problembehandlung

Fehler: Sie sind nicht berechtigt, auf dieses Portal zuzugreifen.

Unter bestimmten Umständen kann die folgende Fehlermeldung angezeigt werden, nachdem sich ein Benutzer mit einem konfigurierten Benutzerkonto beim API Center-Portal angemeldet hat:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Vergewissern Sie sich zunächst, dass dem Benutzer die Rolle Azure API Center-Datenleser in Ihrem API Center zugewiesen ist.

Wenn dem Benutzer die Rolle zugewiesen ist, liegt u. U. ein Problem mit der Registrierung des Ressourcenanbieters Microsoft.ApiCenter in Ihrem Abonnement vor, und Sie müssen 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

Anmeldung beim Portal nicht möglich

Wenn Benutzer, denen die Rolle Azure API Center-Datenleser zugewiesen wurde, den Anmeldevorgang nicht abschließen können, nachdem sie im API Center-Portal die Option Anmelden gewählt haben, liegt möglicherweise ein Problem mit der Konfiguration des Microsoft Entra ID-Identitätsanbieters vor.

Überprüfen Sie in der Microsoft Entra-App-Registrierung die Einstellungen für den Umleitungs-URI, und aktualisieren Sie sie ggf., um sicherzustellen, dass der URI mit dem URI der API Center-Portalbereitstellung übereinstimmt.

Auswahl von Azure API Center-Berechtigungen in der Microsoft Entra-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.

Supportrichtlinie

Im Startrepository für das API Center-Portal können Sie Feedback geben, Features anfordern und Unterstützung bei der Referenzimplementierung des API Center-Portals erhalten.

Zugehöriger Inhalt