Freigeben über

Selbsthosten des API-Verwaltungsentwicklerportals

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

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.

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:

  • Bereitstellung auf einer Hostingplattform, optional mit einer Lösung wie CDN für erhöhte Verfügbarkeit und Leistung
  • Verwalten und Pflegen der Hostinginfrastruktur
  • Manuelle Updates, einschließlich sicherheitsrelevanter Patches, die möglicherweise erfordern, dass Sie Codekonflikte beim Upgrade der Codebasis beheben.

Hinweis

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

Wenn Sie Mediendateien bereits im verwalteten Portal hochgeladen oder geändert haben, lesen Sie " Wechseln von verwalteten zu selbst gehosteten Dateien" 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, müssen Sie das Repository klonen, zur neuesten Version des Entwicklerportals wechseln und npm-Pakete installieren.

  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. Die Softwaretechniker verwenden 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

Das Entwicklerportal erfordert die API-Verwaltungs-REST-API zum Verwalten der Inhalte.

Datei „config.design.json“

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

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

Konfigurieren Sie die Datei:

  1. Ersetzen Sie im managementApiUrl Wert <service-name> durch den Namen Ihrer API-Verwaltungsinstanz. Wenn Sie eine benutzerdefinierte Domäne konfiguriert haben, verwenden Sie sie stattdessen (z. B https://management.contoso.com. ).

    {
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...

  2. Erstellen Sie manuell ein SAS-Token , um den direkten REST-API-Zugriff auf Ihre API-Verwaltungsinstanz zu ermöglichen.

  3. Kopieren Sie das generierte Token, und fügen Sie es als managementApiAccessToken Wert ein.

  4. Ersetzen Sie im backendUrl Wert <service-name> durch den Namen Ihrer API-Verwaltungsinstanz. Wenn Sie eine benutzerdefinierte Domäne konfiguriert haben, verwenden Sie sie stattdessen (z. B https://portal.contoso.com. ).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

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

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

    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",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Konfigurieren Sie die Datei:

  1. Kopieren und Einfügen Sie die managementApiUrl und managementApiAccessToken Werte aus der vorherigen Konfigurationsdatei.

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

Datei „config.runtime.json“

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

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

Konfigurieren Sie die Datei:

  1. Kopieren Sie den managementApiUrl Wert aus der vorherigen Konfigurationsdatei, und fügen Sie ihn ein.

  2. Ersetzen Sie im backendUrl Wert <service-name> durch den Namen Ihrer API-Verwaltungsinstanz. Wenn Sie eine benutzerdefinierte Domäne konfiguriert haben, verwenden Sie sie stattdessen (z. B. https://portal.contoso.com).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

Konfigurieren der statischen Website

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

  1. Wechseln Sie im Azure-Portal zu Ihrem Speicherkonto, und wählen Sie im Menü auf der linken Seite die Option "Statische Website " aus.

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

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

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

  5. Wählen Sie Speichern aus.

Konfigurieren von CORS-Einstellungen für Speicherkonto

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

  1. Wechseln Sie im Azure-Portal zu Ihrem Speicherkonto, und wählen Sie CORS im Menü auf der linken Seite aus.

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

  3. 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 den Portalkonfigurationsdateien festgelegt), um mehrere Features zu aktivieren, darunter:

So fügen Sie CORS-Einstellungen hinzu:

  1. Wechseln Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz, und wählen Sie dieEinstellungen des > im Menü auf der linken Seite aus.
  2. 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://www.contoso.com
    • localhost für die lokale Entwicklung (falls zutreffend), wie http://localhost:8080 oder https://localhost:8080
  3. 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.

Führen Sie den folgenden Befehl aus:

npm start

Nach kurzer 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. Alle Änderungen an der Codebasis des Projekts lösen einen Neubau aus und aktualisieren das Browserfenster.

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: Lokal veröffentlichen

Die Portaldaten liegen ursprünglich als stark typisierte Objekte vor. Der folgende Befehl übersetzt sie in statische Dateien und platziert die Ausgabe im ./dist/website Verzeichnis:

npm run publish

Schritt 6: Hochladen statischer Dateien in ein Blob

Verwenden Sie 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 Azure CLI-Befehl aus.

    Ersetzen Sie <account-connection-string> durch die Verbindungszeichenfolge Ihres Speicherkontos. Sie können dies über den Abschnitt "Zugriffstasten " Ihres Speicherkontos abrufen.

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

Schritt 7: Zur Website wechseln

Ihre Website befindet sich jetzt unter dem Hostnamen, der in Ihren Azure Storage-Eigenschaften angegeben ist (primärer Endpunkt in statischen Websites).

Schritt 8: Ändern von API-Verwaltungsbenachrichtigungsvorlagen

Ersetzen Sie die URL des Entwicklerportals in den API-Verwaltungsbenachrichtigungsvorlagen, um auf Ihr selbst gehostetes Portal zu verweisen. 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>

Einladen des Benutzers

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 beispielsweise zwingen, ein benutzerdefiniertes Widget zu erstellen, das mit einem Drittanbieter-Datenanbieter 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 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 Lernprogramm: Verwendung einer systemzugewiesenen Identität der Linux-VM für den Zugriff auf Azure Storage über SAS-Anmeldedaten, 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