Teilen über

Selbsthosten Ihres API Center-Portals

In diesem Artikel wird gezeigt, wie Sie das API Center-Portal selbst hosten, eine Website, die Entwickler und andere Interessengruppen in Ihrer Organisation verwenden können, um die APIs in Ihrem API Center zu ermitteln. Stellen Sie eine Referenzimplementierung des Portals aus dem START-Repository des API Center-Portals bereit.

Screenshot des API Center-Portals nach der Benutzeranmeldung.

Tipp

Neu! Sie können jetzt eine von Azure verwaltete Version des API Center-Portals einrichten. Weitere Informationen finden Sie unter Einrichten des API Center-Portals.

Informationen zum Self-Hosting des Portals

Sie können eine Referenzimplementierung des Portals mithilfe von Code im START-Repository des API Center-Portals erstellen und bereitstellen. Das Portal verwendet die Azure API Center-Datenebenen-API , um Daten aus Ihrem API-Center abzurufen.

Die API Center-Portalreferenzimplementierung bietet Folgendes:

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

Hinweis

Wenn Sie das API Center-Portal selbst hosten, werden Sie zum Betreuer und sind für seine Upgrades verantwortlich. Der Azure-Support ist eingeschränkt.

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 Azure-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 und die folgenden Tools, die auf Ihrem lokalen Computer installiert sind:

Erstellen der 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.

DAS API Center kann die App-Registrierung automatisch einrichten, oder Sie können die App-Registrierung manuell erstellen.

Automatisches Einrichten der App-Registrierung

Führen Sie die folgenden Schritte aus, um die App-Registrierung automatisch einzurichten:

  1. Navigieren Sie im Azure-Portal zu Ihrem API Center.
  2. Wählen Sie im linken Menü die Api Center-Portaleinstellungen> aus.
  3. Wählen Sie auf der Registerkarte "Identitätsanbieter " die Option "Einrichten starten" aus.
  4. Wählen Sie auf der Registerkarte "Schnelleinrichtung " die Option "Speichern + Veröffentlichen" aus.

Wenn Sie später auf die App-Registrierung zugreifen müssen, finden Sie sie im Portal unter App-Registrierungen. Die Anwendung wird mit dem folgenden Format benannt: <api-center-name-apic-aad>.

Manuelles Einrichten der App-Registrierung

Wenn Sie die App-Registrierung manuell erstellen möchten, führen Sie die folgenden Schritte aus:

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

  2. Wählen Sie + Neue Registrierung aus.

  3. Legen Sie auf der Seite Anwendung registrieren folgende Werte fest:

    1. Festlegen des Namens auf einen aussagekräftigen Namen wie api-center-portal
    2. Wählen Sie unter "Unterstützte Kontotypen" nur "Konten" in diesem Organisationsverzeichnis (<Verzeichnisname> – Einzelner Mandant) aus.
    3. Wählen Sie im Umleitungs-URIdie Einzelseitenanwendung (Single Page Application, SPA) aus, und legen Sie den URI fest. Geben Sie den URI Ihrer API Center-Portalbereitstellung in das folgende Formular ein: https://<service-name>.portal.<location>.azure-apicenter.ms Ersetzen Sie <service name> und <location> durch den Namen Ihres API-Centers und den Ort, an dem es bereitgestellt wird. Beispiel: https://myapicenter.portal.eastus.azure-apicenter.ms.
    4. Wählen Sie Registrieren aus.

Konfigurieren zusätzlicher Umleitungs-URIs für die VS-Codeerweiterung

Konfigurieren Sie beim Aktivieren der API Center-Portalansicht in der Visual Studio Code-Erweiterung für API Center auch die folgenden Umleitungs-URIs in der App-Registrierung:

  1. Navigieren Sie im Azure-Portal zu Ihrer App-Registrierung.

  2. Wählen Sie auf der Seite "Authentifizierung>" die Option "Plattform hinzufügen" und dann "Mobile" und "Desktopanwendungen" aus.

  3. Konfigurieren Sie die folgenden drei benutzerdefinierten Umleitungs-URIs:
    https://vscode.dev/redirect
    http://localhost
    ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>

    Ersetzen Sie <application-client-id> durch die Anwendungs-ID (Client-ID) dieser App. Sie finden diesen Wert auf der Seite "Übersicht" der App-Registrierung.

Hinweis

Wenn Sie das Portal selbst hosten und es vor der Bereitstellung in Azure lokal testen möchten, legen Sie den Umleitungs-URI in der App-Registrierung auf https://localhost:5173.

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 START-Repository des API Center-Portals 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. Sehen Sie sich den Hauptzweig an.

    git checkout main

  4. Um den Dienst zu konfigurieren, kopieren oder umbenennen Sie die public/config.example Datei in public/config.json.

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

    1. Ersetzen Sie <service name> und <location> durch den Namen Ihres API-Centers und den Standort, an dem es bereitgestellt wird.
    2. Ersetzen Sie <client ID> und <tenant ID> mit der Anwendungs-ID (Client-ID) und der Verzeichnis-ID (Mandant) der App-Registrierung, die Sie im vorherigen Abschnitt erstellt haben.
    3. Aktualisieren Sie den Wert von title auf einen Namen, der in der oberen Leiste des Portals angezeigt werden soll.
    {
  "dataApiHostName": "<service name>.data.<location>.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 Sie erforderliche Pakete.

    npm install

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

    npm start

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

Bereitstellen in Azure

Schritte zum Bereitstellen des Portals in Azure Static Web Apps finden Sie im Start-Repository des API Center-Portals .

Aktivieren der Anmeldung beim Portal durch Microsoft Entra-Benutzer und -Gruppen

Um die Anmeldung beim API Center-Portal für den Zugriff auf APIs zu ermöglichen, weisen Sie benutzern oder Gruppen in Ihrer Organisation die Rolle " Azure API Center Data Reader " zu, die auf Ihr API Center ausgerichtet ist.

Von großer Bedeutung

Standardmäßig müssen Sie und andere Administratoren des API Center sich anmelden, um auf APIs im API Center-Portal zuzugreifen. Stellen Sie sicher, dass Sie die Rolle Azure API Center-Datenleser sich selbst und anderen Administratoren zuweisen.

Ausführliche Voraussetzungen und Schritte zum Zuweisen einer Rolle zu Benutzern und Gruppen finden Sie unter Zuweisen von Azure-Rollen mithilfe des Azure-Portals. Kurze Schritte:

  1. Navigieren Sie im Azure-Portal zu Ihrem API Center.
  2. Wählen Sie im linken Menü die Option Access Control (IAM)>+ Rollenzuweisung hinzufügen aus.
  3. Legen Sie im Bereich " Rollenzuweisung hinzufügen " die Werte wie folgt fest:
    1. Suchen und wählen Sie auf der Seite Rolle den Azure API Center-Datenleser aus. Wählen Sie Weiteraus.
    2. Wählen Sie auf der Seite Mitglieder unter Zugriff zuweisen die Option Benutzer, Gruppe oder Dienstprinzipal>+ Mitglieder auswählen aus.
    3. Suchen Sie auf der Seite Mitglieder auswählen nach den Benutzern oder Gruppen, denen die Rolle zugewiesen werden soll, und wählen Sie diese aus. Klicken Sie auf Auswählen und dann auf Weiter.
    4. Ü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 dynamische Gruppenmitgliedschaftsregel 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 API Center-Portal-App-Registrierung angefordert werden. Danach werden andere konfigurierte Benutzer nicht zur Zustimmung aufgefordert.

Problembehandlung

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

Unter bestimmten Bedingungen kann ein Benutzer nach der Anmeldung beim API Center-Portal mit einem konfigurierten Benutzerkonto die folgende Fehlermeldung sehen:

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 des Azure API Center-Datenlesers im API Center zugewiesen ist.

Wenn dem Benutzer die Rolle zugewiesen ist, liegt möglicherweise ein Problem mit der Registrierung des Microsoft.ApiCenter-Ressourcenanbieters in Ihrem Abonnement vor, und Möglicherweise müssen Sie den Ressourcenanbieter erneut registrieren. Führen Sie dazu den folgenden Befehl in der Azure CLI aus:

az provider register --namespace Microsoft.ApiCenter

Anmeldung beim Portal nicht möglich

Wenn Benutzer, denen die Azure API Center Data Reader-Rolle zugewiesen wurde, den Anmeldefluss nach der Auswahl der Anmeldung im API Center-Portal nicht abschließen können, liegt möglicherweise ein Problem bei der Konfiguration des Microsoft Entra ID-Identitätsanbieters vor.

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

Azure API Center-Berechtigungen können in der Microsoft Entra-App-Registrierung nicht ausgewählt werden.

Wenn Sie API-Berechtigungen für das Azure API Center nicht in der Microsoft Entra-App-Registrierung für das Azure API Center-Portal anfordern können, überprüfen Sie, ob Sie nach Azure API Center (oder Anwendungs-ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573) suchen.

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

az provider register --namespace Microsoft.ApiCenter

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

Unterstützungsrichtlinie

Geben Sie Feedback, fordern Sie Features an, und erhalten Sie Unterstützung für die API Center-Portalreferenzimplementierung im START-Repository des API Center-Portals .

Verwandte Inhalte

  • Last updated on