Teilen über

Selbsthosten des API-Verwaltungsentwicklerportals

GILT FÜR: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

In diesem Lernprogramm wird beschrieben, wie Sie das API-Verwaltungsentwicklerportal selbst hosten. Self-Hosting ist eine von mehreren Optionen, um die Funktionalität des Entwicklerportals zu erweitern . Sie können beispielsweise mehrere Portale für Ihre API-Verwaltungsinstanz mit unterschiedlichen Features selbst hosten. Wenn Sie ein Portal selbst hosten, werden Sie zum Betreuer und sind für seine Upgrades verantwortlich. Das Entwicklerportal erfordert die API-Verwaltungs-REST-API zum Verwalten der Inhalte.

Von Bedeutung

Erwägen Sie das Selbsthosting des Entwicklerportals nur, wenn Sie den Kern der Codebasis des Entwicklerportals ändern müssen. Für diese Option ist eine erweiterte Konfiguration erforderlich, einschließlich:

  • Die Bereitstellung auf einer Hostingplattform wird optional von einer Lösung wie einem Content Delivery Network (CDN) begleitet, um die Verfügbarkeit und Leistung zu erhöhen.
  • Pflegen und Verwalten der Hostinginfrastruktur.
  • Manuelle Updates, einschließlich für Sicherheitspatches, die möglicherweise erfordern, dass Sie Codekonflikte beim Upgrade der Codebasis beheben müssen.

Hinweis

Das selbst gehostete Portal unterstützt keine Sichtbarkeit und Zugriffssteuerungen, die im verwalteten Entwicklerportal verfügbar sind.

Wenn Sie bereits Mediendateien im verwalteten Portal hochgeladen oder geändert haben, lesen Sie " Von verwalteter zu selbst gehosteter Datei wechseln", weiter unten in diesem Artikel.

Voraussetzungen

Um eine lokale Entwicklungsumgebung einzurichten, müssen Sie folgendes haben:

Schritt 1: Einrichten einer lokalen Umgebung

Um Ihre lokale Umgebung einzurichten, klonen Sie das Repository, wechseln Sie zur neuesten Version des Entwicklerportals, und installieren Sie npm-Pakete.

  1. Klonen Sie das Api-Management-Entwicklerportal-Repository von GitHub:

    git clone https://github.com/Azure/api-management-developer-portal.git

  2. Wechseln Sie zu Ihrer lokalen Kopie des Repositorys:

    cd api-management-developer-portal

  3. Schauen Sie sich die neueste Version des Portals an.

    Bevor Sie den folgenden Code ausführen, überprüfen Sie das aktuelle Releasetag im Abschnitt "Releases" des Repositorys , und ersetzen <current-release-tag> Sie den Wert durch das neueste Release-Tag.

    git checkout <current-release-tag>

  4. Installieren Sie alle verfügbaren npm-Pakete:

    npm install

Tipp

Verwenden Sie immer das neueste Portalrelease, und halten Sie Ihr geforktes Portal auf dem neuesten Stand. Das API Management-Entwicklungsteam verwendet den master Zweig dieses Repositorys für tägliche Entwicklungszwecke. Es hat instabile Versionen der Software.

Schritt 2: Konfigurieren von JSON-Dateien, statischen Websites und CORS-Einstellungen

Datei „config.design.json“

Wechseln Sie zum src Ordner, und öffnen Sie die config.design.json Datei.

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

Geben Sie in subscriptionId, resourceGroupName und serviceName Werte für das Abonnement, die Ressourcengruppe und den Dienstnamen Ihrer API-Verwaltungsinstanz ein. I

Optionale Einstellungen in config.design.json

Konfigurieren Sie optional die folgenden Einstellungen in der config.design.json Datei:

  1. Wenn Sie CAPTCHA in Ihrem Entwicklerportal aktivieren möchten, legen Sie "useHipCaptcha": true fest. Stellen Sie sicher, dass Sie CORS-Einstellungen für das Back-End des Entwicklerportals konfigurieren.

    {
    ...
    "useHipCaptcha": true
    ...
}

  2. In integration, unter googleFonts, setzen Sie optional apiKey auf einen Google API-Schlüssel, der den Zugriff auf die Web Fonts Developer API ermöglicht. Dieser Schlüssel ist nur erforderlich, wenn Sie Google-Schriftarten im Abschnitt "Formatvorlagen" des Entwicklerportal-Editors hinzufügen möchten.

    {
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}

  3. Wenn Sie noch keinen Schlüssel haben, können Sie einen Schlüssel mithilfe der Google Cloud-Konsole konfigurieren. Folgen Sie diesen Schritten:

    1. Öffnen Sie die Google Cloud-Konsole.
    2. Überprüfen Sie, ob die Webschriftarten-Entwickler-API aktiviert ist. Wenn dies nicht der Grund ist, aktivieren Sie sie.
    3. Wählen Sie Anmeldeinformationen erstellen>API-Schlüssel aus.
    4. Kopieren Sie im Dialogfeld "Öffnen" den generierten Schlüssel, und fügen Sie ihn als Wert apiKey in der config.design.json Datei ein.
    5. Wählen Sie "API-Schlüssel bearbeiten" aus, um den Schlüssel-Editor zu öffnen.
    6. Wählen Sie im Editor unter API-Einschränkungendie Option "Schlüssel einschränken" aus. Wählen Sie in der Dropdownliste die Webschriftarten-Entwickler-API aus.
    7. Wählen Sie Speichern aus.

Datei „config.publish.json“

Wechseln Sie zum src Ordner, und öffnen Sie die config.publish.json Datei.

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Kopieren und fügen Sie die Werte von subscriptionId, resourceGroupName und serviceName aus der vorherigen Konfigurationsdatei ein.

Datei „config.runtime.json“

Wechseln Sie zum src Ordner, und öffnen Sie die config.runtime.json Datei.

{
    "environment": "runtime",
    "backendUrl": "https://< service name >.developer.azure-api.net"
}

Ersetzen Sie < service name > durch den Namen Ihrer API-Verwaltungsinstanz, die in den vorherigen Konfigurationsdateien verwendet wurde.

Konfigurieren der statischen Website

Konfigurieren Sie das Feature "Statische Website " in Ihrem Speicherkonto, indem Sie Routen zu den Index- und Fehlerseiten bereitstellen:

  1. Navigieren Sie im Azure-Portal zu Ihrem Speicherkonto.

  2. Wählen Sie im Seitenmenü die Option Data management>Statische Website aus.

  3. Wählen Sie auf der Seite "Statische Website" die Option "Aktiviert" aus.

  4. Geben Sie im Feld "Indexdokumentname " index.htmlein.

  5. Geben Sie im Feld "Fehlerdokumentpfad" 404/index.htmlein.

  6. Wählen Sie Speichern aus.

Notieren Sie sich die URL des primären Endpunkts . Sie konfigurieren es später für den Zugriff auf Ihr selbst gehostetes Portal.

Konfigurieren von CORS-Einstellungen für Speicherkonto

So konfigurieren Sie die CORS-Einstellungen (Cross-Origin Resource Sharing) für das Speicherkonto:

  1. Wechseln Sie im Azure-Portal zu Ihrem Speicherkonto.

  2. Wählen Sie im Randleistenmenü unter "Einstellungen" die Option "Ressourcenfreigabe ( CORS)" aus.

  3. Konfigurieren Sie auf der Registerkarte Blob-Dienst die folgenden Regeln:

    Regel Wert
    Zulässige Ursprünge *
    Zulässige Methoden Wählen Sie alle HTTP-Verben aus.
    Zulässige Header *
    Verfügbar gemachte Header *
    Maximales Alter 0

  4. Wählen Sie Speichern aus.

Konfigurieren von CORS-Einstellungen für das Back-End des Entwicklerportals

Konfigurieren Sie CORS-Einstellungen für das Entwicklerportal-Back-End, um Anforderungen zuzulassen, die über Ihr selbst gehostetes Entwicklerportal stammen. Das selbst gehostete Entwicklerportal basiert auf dem Back-End-Endpunkt des Entwicklerportals (in backendUrl der Portaldatei config.runtime.json festgelegt), um mehrere Features zu aktivieren, darunter:

So fügen Sie CORS-Einstellungen hinzu:

  1. Wechseln Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.
  2. Wählen Sie im Randleistenmenü dieEinstellungen des > aus.
  3. Fügen Sie auf der Registerkarte "Selbst gehostete Portalkonfiguration " einen oder mehrere Origin-Domänenwerte hinzu. Beispiel:
    • Die Domäne, in der das selbst gehostete Portal gehostet wird, z. B. https://contoso.developer.azure-api.net
    • localhost für die lokale Entwicklung (falls zutreffend), wie http://localhost:8080 oder https://localhost:8080
  4. Wählen Sie Speichern aus.

Schritt 3: Ausführen des Portals

Jetzt können Sie eine lokale Portalinstanz im Entwicklungsmodus erstellen und ausführen. Im Entwicklungsmodus werden alle Optimierungen deaktiviert, und die Quellzuordnungen sind aktiviert.

  1. Führen Sie den folgenden Befehl aus:

    npm run start

  2. Sie werden aufgefordert, sich über Ihren Browser zu authentifizieren. Wählen Sie Ihre Microsoft-Anmeldeinformationen aus, um den Vorgang fortzusetzen.

  3. Nach einiger Zeit wird der Standardbrowser automatisch mit Ihrer lokalen Entwicklerportalinstanz geöffnet. Die Standardadresse lautet http://localhost:8080, aber der Port kann sich ändern, wenn 8080 sie bereits belegt ist. Wenn Sie Änderungen an der Codebasis des Projekts vornehmen, wird eine Neuerstellung ausgelöst und das Browserfenster aktualisiert.

Schritt 4: Bearbeiten des visuellen Editors

Verwenden Sie den visuellen Editor, um diese Aufgaben auszuführen:

  • Anpassen Ihres Portals
  • Erstellen von Inhalt
  • Struktur der Website organisieren
  • Gestalten der Darstellung

Siehe Lernprogramm: Zugreifen und Anpassen des Entwicklerportals. Es behandelt die Grundlagen der Administrativen Benutzeroberfläche und listet empfohlene Änderungen am Standardinhalt auf. Speichern Sie alle Änderungen in der lokalen Umgebung, und drücken Sie STRG+C , um sie zu schließen.

Schritt 5: Lokales Veröffentlichen des Portals

  1. Führen Sie npm run publish aus. Sie werden aufgefordert, sich über Ihren Browser zu authentifizieren. Wählen Sie Ihre Microsoft-Anmeldeinformationen aus, um den Vorgang fortzusetzen.

  2. Nach einiger Zeit wird der Inhalt im dist/website Ordner veröffentlicht.

Schritt 6: Hochladen statischer Dateien in ein Blob

Verwenden Sie die Azure CLI, um die lokal generierten statischen Dateien in ein Blob hochzuladen, und stellen Sie sicher, dass Ihre Besucher darauf zugreifen können:

  1. Öffnen Sie die Windows-Eingabeaufforderung, PowerShell oder eine andere Befehlsshell.

  2. Führen Sie den folgenden az storage blog upload-batch Befehl aus. Ersetzen Sie <connection-string> durch eine Verbindungszeichenfolge für Ihr Speicherkonto. Sie könnendies über den Abschnitt >" Ihres Speicherkontos abrufen.

    az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"

Schritt 7: Zur Website wechseln

Ihre Website befindet sich jetzt unter dem Hostnamen, der in Ihren Azure Storage-Eigenschaften angegeben ist. Wechseln Sie im Randleistenmenü zurStatischen Website für >. Der Hostname ist der Wert des primären Endpunkts.

Hosten des Website-Editors

Wenn Sie Änderungen am Websitecode vornehmen, müssen Sie möglicherweise auch den Website-Editor-Code aktualisieren, um die Bearbeitung Ihrer geänderten Widgets ordnungsgemäß unterstützen zu können. In diesem Fall können Sie neben dem Hosten des Portals auch die Editoranwendung hosten. Dazu müssen Sie sie erstellen und konfigurieren, um auf Ihren API-Verwaltungsdienst zuzugreifen.

Dazu benötigen Sie eine Microsoft Entra-ID-Anwendung in Ihrem Mandanten:

  1. Registrieren Sie eine Anwendung in Ihrem Microsoft Entra ID-Mandanten. Notieren Sie sich die Anwendungs-ID (Client-ID) und die Verzeichnis-ID (Mandanten-ID). Sie konfigurieren sie in einem späteren Schritt.
  2. Konfigurieren Sie einen Webumleitungs-URI (Antwort-URL) in dieser Anwendung so, dass er auf den Endpunkt der Web-App verweist, in der der Designer gehostet wird. Dies ist in der Regel der Standort der Website, die auf Blob Storage basiert. Beispiel: https://<your-storage-account-name>z13.web.core.windows.net/.
  3. Wenn Sie das Portal in Pipelines (GitHub-Aktionen) veröffentlichen möchten, erstellen Sie auch einen geheimen Clientschlüssel für diese Anwendung. Notieren Sie sich den generierten geheimen Wert, und speichern Sie ihn an einem sicheren Ort.

Führen Sie dann die folgenden Schritte aus, um den Website-Editor zu hosten:

  1. Fügen Sie die Felder clientId und tenantId zur config.design.json-Datei hinzu.

    {
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

  2. Führen Sie den Befehl aus, um den Designer npm run build-designer zu erstellen.

  3. Wechseln Sie zum generierten /dist/designer Ordner, der eine Datei config.json mit dem folgenden Inhalt enthält:

    {
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

  4. Bestätigen Sie die Konfiguration von subscriptionId, resourceGroupName und serviceName, die für die Verbindung mit Ihrem API-Verwaltungsdienst über Azure Resource Manager-APIs erforderlich sind.

Veröffentlichen des Portals in Pipelines (GitHub-Aktionen)

Sie können das selbst gehostete Portal in einer Pipeline wie GitHub-Aktionen veröffentlichen.

Die Pipeline benötigt außerdem Entra-ID-Anwendungsanmeldeinformationen, um die Veröffentlichung mithilfe von Pipelines auszuführen. Sie können dieselbe Entra-ID-Anwendung verwenden, die in den vorherigen Schritten beschrieben wird. Die tenantId, clientId und insbesondere clientSecret müssen in den jeweiligen Schlüsselspeichern gespeichert werden. Weitere Details finden Sie zur Verwendung von Geheimnissen in GitHub-Aktionen.

Beispiel für die GitHub Actions-Pipeline YAML:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

Ändern von API-Verwaltungsbenachrichtigungsvorlagen

Ersetzen Sie die ENTWICKLERportal-URL in den API-Verwaltungsbenachrichtigungsvorlagen, sodass sie auf Ihr selbst gehostetes Portal verweist. Siehe So konfigurieren Sie Benachrichtigungen und E-Mail-Vorlagen in Azure API Management.

Führen Sie insbesondere die folgenden Änderungen an den Standardvorlagen aus:

Hinweis

Die Werte in den folgenden Aktualisierten Abschnitten gehen davon aus, dass Sie das Portal unter https://portal.contoso.com/hosten.

Bestätigung der E-Mail-Änderung

Aktualisieren Sie die URL des Entwicklerportals in der E-Mail-Änderungsbestätigungsbenachrichtigungsvorlage :

Ursprünglicher Inhalt

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Aktualisiert

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Bestätigung für neues Entwicklerkonto

Aktualisieren Sie die URL des Entwicklerportals in der Bestätigungsbenachrichtigungsvorlage "Neues Entwicklerkonto ":

Ursprünglicher Inhalt

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Aktualisiert

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Benutzer einladen

Aktualisieren Sie die URL des Entwicklerportals in der Vorlage " Benutzerbenachrichtigung einladen ":

Ursprünglicher Inhalt

<a href="$ConfirmUrl">$ConfirmUrl</a>

Aktualisiert

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Neues Abonnement aktiviert

Aktualisieren Sie die URL des Entwicklerportals in der Vorlage für aktivierte Benachrichtigungen " Neues Abonnement ":

Ursprünglicher Inhalt

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Aktualisiert

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Ursprünglicher Inhalt

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Aktualisiert

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Ursprünglicher Inhalt

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Aktualisiert

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Ursprünglicher Inhalt

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

Aktualisiert

<!--Remove the entire block of HTML code above.-->

Bestätigung der Kennwortänderung

Aktualisieren Sie die URL des Entwicklerportals in der Bestätigungsbenachrichtigungsvorlage für Kennwortänderung :

Ursprünglicher Inhalt

<a href="$DevPortalUrl">$DevPortalUrl</a>

Aktualisiert

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Alle Vorlagen

Aktualisieren Sie die URL des Entwicklerportals in jeder Vorlage, die über einen Link in der Fußzeile verfügt:

Ursprünglicher Inhalt

<a href="$DevPortalUrl">$DevPortalUrl</a>

Aktualisiert

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

Wechseln vom verwalteten zu selbst gehosteten Entwicklerportal

Im Laufe der Zeit können sich Ihre Geschäftlichen Anforderungen ändern. Sie können in einer Situation enden, in der die verwaltete Version des API Management-Entwicklerportals Ihre Anforderungen nicht mehr erfüllt. Eine neue Anforderung kann Sie z. B. zwingen, ein benutzerdefiniertes Widget zu entwickeln, das mit einem Drittanbieterdatenanbieter integriert wird. Im Gegensatz zur verwalteten Version bietet ihnen die selbst gehostete Version des Portals volle Flexibilität und Erweiterbarkeit.

Übergangsprozess

Sie können von der verwalteten Version zu einer selbst gehosteten Version innerhalb derselben API-Verwaltungsdienstinstanz wechseln. Der Prozess behält die Änderungen bei, die Sie in der verwalteten Version des Portals durchgeführt haben. Stellen Sie sicher, dass Sie den Inhalt des Portals vorab sichern. Sie finden das Sicherungsskript im scripts.v3 Ordner des GitHub-Repositorys des API Management-Entwicklerportals.

Der Konvertierungsprozess ist fast identisch mit dem Einrichten eines generischen selbst gehosteten Portals, wie in den vorherigen Schritten in diesem Artikel gezeigt. Im Konfigurationsschritt gibt es eine Ausnahme. Das Speicherkonto in der config.design.json Datei muss mit dem Speicherkonto der verwalteten Version des Portals übereinstimmen. Siehe das Tutorial: Verwenden einer vom Linux-VM zugewiesenen Identität für den Zugriff auf Azure Storage über SAS-Zugangsdaten, um Anweisungen zum Abrufen der SAS-URL zu erhalten.

Tipp

Es wird empfohlen, ein separates Speicherkonto in der config.publish.json Datei zu verwenden. Dieser Ansatz bietet Ihnen mehr Kontrolle und vereinfacht die Verwaltung des Hostingdiensts Ihres Portals.

Verwandte Inhalte

  • Last updated on