Selbsthosten des API Management-Entwicklerportals

  • Artikel

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

In diesem Tutorial erfahren Sie, wie Sie das API Management-Entwicklerportal selbst hosten. Das Selbsthosten ist eine von mehreren Optionen zum Erweitern der Funktionalität des Entwicklerportals. Beispielsweise können Sie mehrere Portale für Ihre API Management-Instanz mit jeweils unterschiedlichen Features selbst hosten. Wenn Sie ein Portal selbsthosten, sind Sie der Verwalter und für Upgrades verantwortlich.

Wichtig

Erwägen Sie das Selbsthosten des Entwicklerportals nur dann, wenn Sie den Kern der Codebasis des Entwicklerportals ändern müssen. Für diese Option ist eine erweiterte Konfiguration erforderlich, die Folgendes umfasst:

  • Bereitstellung auf einer Hostingplattform, der für höhere Verfügbarkeit und Leistung optional eine Lösung wie CDN vorangestellt wird
  • Warten und Verwalten der Hostinginfrastruktur
  • Manuelle Updates, einschließlich Sicherheitspatches, die möglicherweise das Beheben von Codekonflikten beim Upgrade der Codebasis erfordern

Hinweis

Das selbstgehostete Portal unterstützt keine Sichtbarkeits- und Zugriffssteuerelemente, die im verwalteten Entwicklerportal verfügbar sind.

Wenn Sie bereits Mediendateien im verwalteten Portal hochgeladen oder geändert haben, lesen Sie den Abschnitt Wechseln von einem verwalteten zu einem selbstgehosteten Entwicklerportal weiter unten in diesem Artikel.

Voraussetzungen

Zum Einrichten einer lokalen Entwicklungsumgebung benötigen Sie Folgendes:

Schritt 1: Einrichten der lokalen Umgebung

Die Einrichtung Ihrer lokalen Umgebung umfasst das Klonen des Repositorys, den Wechsel zur neuesten Version des Entwicklerportals und die Installation von npm-Paketen.

  1. Klonen Sie das Repository api-management-developer-portal aus GitHub:

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

  2. Navigieren Sie zu Ihrer lokalen Kopie des Repositorys:

    cd api-management-developer-portal

  3. Checken Sie das neueste Release des Portals aus.

    Überprüfen Sie vor dem Ausführen des folgenden Codes das aktuelle Releasetag im Abschnitt „Releases“ des Repositorys, und ersetzen Sie <current-release-tag> durch das neueste Releasetag.

    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 Softwareentwickler verwenden den Branch master dieses Repositorys für die alltägliche Entwicklung. Er enthält instabile Versionen der Software.

Schritt 2: Konfigurieren von JSON-Dateien, statischer Website und CORS-Einstellungen

Für das Entwicklerportal wird die REST-API von API Management benötigt, um den Inhalt zu verwalten.

Datei „config.design.json“

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

{
  "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 <service-name> im Wert managementApiUrl durch den Namen Ihrer API Management-Instanz. Sollten Sie eine benutzerdefinierte Domäne konfiguriert haben, verwenden Sie stattdessen diese Domäne (beispielsweise 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 Management-Instanz zu ermöglichen.

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

  4. Ersetzen Sie <service-name> im Wert backendUrl durch den Namen Ihrer API Management-Instanz. Sollten Sie eine benutzerdefinierte Domäne konfiguriert haben, verwenden Sie stattdessen diese Domäne (beispielsweise 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 Entwicklerportal-Back-End konfigurieren.

  6. Legen Sie in integration unter googleFonts optional apiKey auf einen Google-API-Schlüssel fest, der den Zugriff auf die Webschriftartenentwickler-API zulässt. Dieser Schlüssel ist nur erforderlich, wenn Sie Google-Schriftarten im Abschnitt „Formatvorlagen“ des Entwicklerportal-Editors hinzufügen möchten.

    Wenn Sie noch nicht über einen Schlüssel verfügen, können Sie einen Schlüssel mithilfe der Google Cloud-Konsole konfigurieren. Führen Sie die folgenden Schritte aus:

    1. Öffnen Sie die Google Cloud-Konsole.
    2. Überprüfen Sie, ob die Webschriftartenentwickler-API aktiviert ist. Ist sie nicht aktiviert, aktivieren Sie sie.
    3. Wählen Sie Anmeldeinformationen erstellen>API-Schlüssel aus.
    4. Kopieren Sie im Geöffneten Dialogfeld den generierten Schlüssel, und fügen Sie ihn als Wert von apiKey in die 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änkungen die Option Schlüssel einschränken aus. Wählen Sie in der Dropdownliste Webschriftartenentwickler-API aus.
    7. Wählen Sie Speichern aus.

Datei „config.publish.json“

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

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Konfigurieren Sie die Datei:

  1. Kopieren Sie die Werte von managementApiUrl und managementApiAccessToken aus der vorherigen Konfigurationsdatei, und fügen Sie sie ein.

  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 Entwicklerportal-Back-End konfigurieren.

Datei „config.runtime.json“

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

{
  "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 Wert von managementApiUrl aus der vorherigen Konfigurationsdatei, und fügen Sie ihn ein.

  2. Ersetzen Sie <service-name> im Wert backendUrl durch den Namen Ihrer API Management-Instanz. Sollten Sie eine benutzerdefinierte Domäne konfiguriert haben, verwenden Sie stattdessen diese Domäne (beispielsweise 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 angeben:

  1. Navigieren 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 Name des Indexdokuments den Namen index.html ein.

  4. Geben Sie im Feld Pfad zum Fehlerdokument die Zeichenfolge 404/index.html ein.

  5. Wählen Sie Speichern aus.

Konfigurieren von CORS-Einstellungen für ein Speicherkonto

Konfigurieren der Einstellungen für die Ressourcenfreigabe zwischen verschiedenen Ursprüngen (Cross-Origin Resource Sharing, CORS):

  1. Navigieren Sie im Azure-Portal zu Ihrem Speicherkonto, und wählen Sie im Menü auf der linken Seite die Option CORS 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 Entwicklerportal-Back-End

Konfigurieren Sie CORS-Einstellungen für das Entwicklerportal-Back-End, um Anforderungen zuzulassen, die aus Ihrem selbstgehosteten Entwicklerportal stammen. Das selbstgehostete Entwicklerportal basiert auf dem Back-End-Endpunkt des Entwicklerportals (in den Portalkonfigurationsdateien in backendUrl festgelegt), um mehrere Features zu aktivieren, einschließlich:

So fügen Sie CORS-Einstellungen hinzu

  1. Wechseln Sie zu Ihrer API Management-Instanz im Azure-Portal, und wählen Sie im linken Menü Entwicklerportal>Portaleinstellungen aus.
  2. Fügen Sie auf der Registerkarte Selbstgehostete Portalkonfiguration einen oder mehrere Werte für die Ursprungsdomäne hinzu. Beispiel:
    • Die Domäne, in der das selbstgehostete Portal gehostet wird, z. B. https://www.contoso.com.
    • localhost für die lokale Entwicklung (falls zutreffend), z. B. http://localhost:8080 oder https://localhost:8080.
  3. Wählen Sie Speichern aus.

Schritt 3: Ausführen des Portals

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

Führen Sie den folgenden Befehl aus:

npm start

Nach kurzer Zeit wird der Standardbrowser automatisch mit Ihrer lokalen Instanz des Entwicklerportals geöffnet. Die Standardadresse lautet http://localhost:8080, der Port kann sich allerdings ändern, falls 8080 bereits belegt ist. Alle Änderungen an der Codebasis des Projekts lösen eine Neuerstellung und die Aktualisierung Ihres Browserfensters aus.

Schritt 4: Bearbeiten über den visuellen Editor

Führen Sie mithilfe des visuellen Editors die folgenden Aufgaben durch:

  • Anpassen Ihres Portals
  • Erstellen von Inhalt
  • Strukturieren der Website
  • Gestalten der Darstellung

Weitere Informationen finden Sie im Tutorial Zugreifen auf und Anpassen des Entwicklerportals. Darin werden die Grundlagen der administrativen Benutzeroberfläche behandelt und empfohlene Änderungen für den Standardinhalt aufgeführt. Speichern Sie alle Änderungen in der lokalen Umgebung, und drücken Sie STRG+C, um sie zu schließen.

Schritt 5: Lokales Veröffentlichen

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

npm run publish

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 auf sie 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 finden sie im Abschnitt Zugriffsschlüssel Ihres Speicherkontos.

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

Schritt 7: Aufrufen Ihrer Website

Ihre Website ist jetzt unter dem Hostnamen verfügbar, der in Ihren Azure Storage-Eigenschaften angegeben ist (Primärer Endpunkt unter Statische Websites).

Schritt 8: Ändern der API Management-Benachrichtigungsvorlagen

Ersetzen Sie die URL des Entwicklerportals in API Management-Benachrichtigungsvorlagen, um auf Ihr selbstgehostetes Portal zu verweisen. Weitere Informationen finden Sie unter Konfigurieren von Benachrichtigungen und E-Mail-Vorlagen in Azure API Management.

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

Hinweis

Bei den Werten in den folgenden Abschnitten vom Typ Aktualisiert wird davon ausgegangen, dass Sie das Portal unter https://portal.contoso.com/ hosten.

Bestätigung der Änderung der E-Mail-Adresse

Aktualisieren Sie die URL des Entwicklerportals in der Benachrichtigungsvorlage Email change confirmation (Bestätigung der Änderung der E-Mail-Adresse):

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 Benachrichtigungsvorlage New developer account confirmation (Bestätigung für 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 Benachrichtigungsvorlage Benutzer 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 Benachrichtigungsvorlage für Neues Abonnement aktiviert:

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 Benachrichtigungsvorlage Password change confirmation (Bestätigung der 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 mit einem Link in der Fußzeile:

Ursprünglicher Inhalt

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

Aktualisiert

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

Wechseln von einem verwalteten zu einem selbstgehosteten Entwicklerportal

Im Laufe der Zeit ändern sich möglicherweise Ihre geschäftlichen Anforderungen. Dadurch kann sich eine Situation ergeben, in der die verwaltete Version des Entwicklerportals für API Management Ihre Anforderungen nicht mehr erfüllt. Eine neue Anforderung kann beispielsweise die Erstellung eines benutzerdefinierten Widgets für die Integration eines externen Datenanbieters erforderlich machen. Im Gegensatz zur verwalteten Version bietet Ihnen die selbstgehostete Version des Portals uneingeschränkte Flexibilität und Erweiterbarkeit.

Übergangsprozess

Sie können innerhalb der gleichen API Management-Dienstinstanz von der verwalteten Version auf eine selbstgehostete Version umsteigen. Bei diesem Prozess bleiben die Änderungen erhalten, die Sie in der verwalteten Version des Portals vorgenommen haben. Erstellen Sie vorab unbedingt eine Sicherung des Portalinhalts. Das Sicherungsskript befindet sich im Ordner scripts des GitHub-Repositorys für das API Management-Entwicklerportal.

Der Konvertierungsprozess ist nahezu identisch mit der Einrichtung eines generischen selbstgehosteten Portals, die in den vorherigen Schritten in diesem Artikel gezeigt wurde. Es gibt allerdings eine Ausnahme im Konfigurationsschritt. Das Speicherkonto in der Datei config.design.json muss dem Speicherkonto der verwalteten Version des Portals entsprechen. Eine Anleitung zum Abrufen der SAS-URL finden Sie im Tutorial Verwenden einer systemseitig zugewiesenen verwalteten Identität eines virtuellen Linux-Computers für den Zugriff auf Azure Storage mithilfe von SAS-Anmeldeinformationen.

Tipp

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

Nächste Schritte