Erweitern des Entwicklerportals durch benutzerdefinierte Widgets

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

Das API Management-Entwicklerportal verfügt über einen visuellen Editor und integrierte Widgets, damit Sie die Darstellung und den Stil des Portals anpassen können. Möglicherweise müssen Sie das Entwicklerportal jedoch darüber hinaus auch durch benutzerdefinierte Funktionen anpassen. Beispielsweise können Sie Ihr Entwicklerportal in ein Supportsystem integrieren, wozu eine benutzerdefinierte Schnittstelle hinzugefügt werden muss. In diesem Artikel wird erläutert, wie Sie Ihrem API Management-Entwicklerportal benutzerdefinierte Funktionen wie benutzerdefinierte Widgets hinzufügen.

In der folgenden Tabelle werden zwei Optionen zusammengefasst und Links zu weiteren Details bereitgestellt.

Verwenden eines benutzerdefinierten HTML-Code-Widgets

Das verwaltete Entwicklerportal umfasst ein Widget Benutzerdefinierter HTML-Code, in dem Sie HTML-Code für kleine Portalanpassungen einfügen können. Verwenden Sie beispielsweise benutzerdefinierten HTML-Code, um ein Video einzubetten oder ein Formular hinzuzufügen. Das Portal rendert das benutzerdefinierte Widget in einem Inlineframe (iframe).

1. Wechseln Sie auf der Verwaltungsoberfläche für das Entwicklerportal zu der Seite oder dem Abschnitt, auf der bzw. in dem Sie das Widget einfügen möchten.

2. Wählen Sie das graue Pluszeichen (+) aus, das angezeigt wird, wenn Sie mit dem Mauszeiger auf die Seite zeigen.

3. Wählen Sie im Fenster Widget hinzufügen die Option Benutzerdefinierter HTML-Code aus.

   

4. Wählen Sie das Stiftsymbol aus, um das Widget anzupassen.

5. Geben Sie eine Breite und Höhe (in Pixel) für das Widget ein.

6. Um Stile vom Entwicklerportal zu erben (empfohlen), wählen Sie Apply developer portal styling (Stile des Entwicklerportals anwenden) aus.

   Hinweis

   Wenn diese Einstellung nicht ausgewählt wird, handelt es sich bei den eingebetteten Elementen um unformatierte HTML-Steuerelemente ohne die Stile des Entwicklerportals.

   

7. Ersetzen Sie den HTML-Beispielcode durch Ihre benutzerdefinierten Inhalte.

8. Schließen Sie das Fenster nach Abschluss der Konfiguration.

9. Speichern Sie Ihre Änderungen, und veröffentlichen Sie das Portal erneut.

Erstellen und Hochladen eines benutzerdefinierten Widgets

Für komplexere Anwendungsfälle können Sie ein benutzerdefiniertes Widget erstellen und in das Entwicklerportal hochladen. API Management stellt ein Codegerüst bereit, mit dem Entwickler benutzerdefinierte Widgets in React, Vue oder einfachem TypeScript erstellen können. Das Gerüst enthält Tools, mit denen Sie Ihr Widget entwickeln und im Entwicklerportal bereitstellen können.

Voraussetzungen

• Lokale Installation der Node.JS-Runtime
• Grundlegende Kenntnisse zur Programmierung und Webentwicklung

Erstellen eines Widgets

1. Wählen Sie in der Verwaltungsschnittstelle des Entwicklerportals Benutzerdefinierte Widgets>Neues benutzerdefiniertes Widget erstellen aus.

2. Geben Sie einen Widgetnamen ein, und wählen Sie eine Technologie aus. Weitere Informationen finden Sie weiter unten in diesem Artikel unter Widgetvorlagen.

3. Wählen Sie Widget erstellen aus.

4. Öffnen Sie ein Terminal, navigieren Sie zu dem Speicherort, an dem Sie den Widgetcode speichern möchten, und führen Sie den folgenden Befehl aus, um das Codegerüst herunterzuladen:

   npx @azure/api-management-custom-widgets-scaffolder
   

5. Navigieren Sie zum neu erstellten Ordner, der das Codegerüst des Widgets enthält.

   cd <name-of-widget>
   

6. Öffnen Sie den Ordner im Code-Editor Ihrer Wahl, z. B. VS Code.

7. Installieren Sie die Abhängigkeiten, und starten Sie das Projekt:

   npm install 
   npm start
   

   Ihr Browser sollte eine neue Registerkarte mit Ihrem Entwicklerportal, das mit Ihrem Widget verbunden ist, im Entwicklungsmodus öffnen.

   Hinweis

   Wenn die Registerkarte nicht geöffnet wird, gehen Sie folgendermaßen vor:

   1. Stellen Sie sicher, dass der Entwicklungsserver gestartet wurde. Überprüfen Sie dazu die Ausgabe auf der Konsole, in der Sie den Server im vorherigen Schritt gestartet haben. Sie sollte den Port anzeigen, auf dem der Server ausgeführt wird (Beispiel: http://127.0.0.1:3001).
   2. Wechseln Sie zum API Management-Dienst im Azure-Portal, und öffnen Sie Ihr Entwicklerportal mit der Verwaltungsschnittstelle.
   3. Fügen Sie /?MS_APIM_CW_localhost_port=3001 an die URL an. Ändern Sie die Portnummer, wenn Ihr Server auf einem anderen Port ausgeführt wird.

8. Implementieren Sie den Code des Widgets, und testen Sie es lokal. Der Code des Widgets befindet sich im Ordner src in den folgenden Unterordnern:

   • app – Code für die Widgetkomponente, die Besuchern des veröffentlichten Entwicklerportals angezeigt wird und mit der sie interagieren
   • editor – Code für die Widgetkomponente, die Sie in der Verwaltungsschnittstelle des Entwicklerportals verwenden, um Widgeteinstellungen zu bearbeiten

   Die Datei values.ts enthält die Standardwerte und Typen der benutzerdefinierten Eigenschaften des Widgets, die Sie für die Bearbeitung aktivieren können.

   

   Anhand benutzerdefinierter Eigenschaften können Sie Werte in der Instanz des benutzerdefinierten Widgets über die Verwaltungsbenutzeroberfläche des Entwicklerportals anpassen, ohne den Code zu ändern oder das benutzerdefinierte Widget erneut bereitzustellen. Dieses Objekt muss an einige Hilfsfunktionen des Widgets übergeben werden.

Bereitstellen des benutzerdefinierten Widgets im Entwicklerportal

1. Geben Sie die folgenden Werte in der Datei deploy.js an, die sich im Stamm Ihres Projekts befindet:

   • resourceId – Ressourcen-ID Ihres API Management-Diensts im folgenden Format: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

   • managementApiEndpoint – Azure Management API-Endpunkt (abhängig von Ihrer Umgebung, normalerweise management.azure.com)

   • apiVersion – Optional, zum Außerkraftsetzen der Management API-Standardversion

2. Führen Sie den folgenden Befehl aus:

   npm run deploy
   

   Melden Sie sich nach Aufforderung bei Ihrem Azure-Konto an.

   Hinweis

   Wenn Sie aufgefordert werden, sich anzumelden, müssen Sie ein Mitgliedskonto aus dem Microsoft Entra ID-Mandanten verwenden, der dem Azure-Abonnement mit Ihrem API Management-Dienst zugeordnet ist. Das Konto darf kein Gast- oder Verbundkonto sein und muss über die entsprechende Berechtigung für den Zugriff auf die Verwaltungsschnittstelle des Portals verfügen.

Das benutzerdefinierte Widget wird jetzt im Entwicklerportal bereitgestellt. Mithilfe der Verwaltungsschnittstelle des Portals können Sie es auf Seiten im Entwicklerportal hinzufügen und Werte für die im Widget konfigurierten benutzerdefinierten Eigenschaften festlegen.

Veröffentlichen des Entwicklerportals

Nachdem Sie das Widget in der Verwaltungsschnittstelle konfiguriert haben, veröffentlichen Sie das Portal erneut, um das Widget in der Produktion verfügbar zu machen.

Widgetvorlagen

Wir stellen Vorlagen für die folgenden Technologien bereit, die Sie für das Widget verwenden können:

• TypeScript (reine Implementierung ohne Framework)
• React
• Vue

Alle Vorlagen basieren auf der TypeScript-Programmiersprache.

Die React-Vorlage enthält vorbereitete benutzerdefinierte Hooks in der Datei hooks.ts und gängige Anbieter zum Freigeben des Kontexts über die Komponentenstruktur mit den dedizierten Hooks useSecrets, useValues und useEditorValues.

Verwenden des Pakets @azure/api-management-custom-widgets-tools

Dieses npm-Paket enthält die folgenden Funktionen, die Sie bei der Entwicklung Ihres benutzerdefinierten Widgets unterstützen, und stellt Features zur Kommunikation zwischen dem Entwicklerportal und Ihrem Widget bereit:

@azure/api-management-custom-widgets-tools/getValues

Diese Funktion gibt ein JSON-Objekt mit den Werten, die Sie im Widget-Editor festgelegt haben, kombiniert mit Standardwerten zurück, die als Argument übergeben werden.

Import {getValues} from "@azure/api-management-custom-widgets-tools/getValues" 
import {valuesDefault} from "./values" 
const values = getValues(valuesDefault) 

Sie ist für die Verwendung im Runtimeteil (app) Ihres Widgets vorgesehen.

@azure/api-management-custom-widgets-tools/getEditorValues

Diese Funktion arbeitet in derselben Weise wie getValues, gibt jedoch nur Werte zurück, die Sie im Editor festgelegt haben.

Sie ist für die Verwendung im Editor Ihres Widgets vorgesehen, funktioniert aber auch in der Runtime.

@azure/api-management-custom-widgets-tools/buildOnChange

Akzeptiert einen TypeScript-Typ und gibt eine Funktion zum Aktualisieren der Widgetwerte zurück. Die zurückgegebene Funktion verwendet als Parameter ein JSON-Objekt mit aktualisierten Werten und gibt keine Werte zurück.

import {Values} from "./values"
const onChange = buildOnChange<Values>()
onChange({fieldKey: 'newValue'})

@azure/api-management-custom-widgets-tools/askForSecrets

Diese Funktion gibt eine JavaScript-Zusage zurück, die nach Auflösung ein JSON-Objekt von Daten zurückgibt, die für die Kommunikation mit dem Back-End erforderlich sind. token ist für die Authentifizierung erforderlich. userId wird benötigt, um benutzerspezifische Ressourcen abzufragen. Diese Werte sind möglicherweise nicht definiert, wenn das Portal von einem anonymen Benutzer angezeigt wird. Das Objekt Secrets enthält auch managementApiUrl, die URL des Back-Ends Ihres Portals und apiVersion, die apiVersion, die derzeit vom Entwicklerportal verwendet wird.

@azure/api-management-custom-widgets-tools/deployNodeJs

Diese Funktion stellt Ihr Widget in Ihrem Blobspeicher bereit. In allen Vorlagen ist sie in der Datei deploy.js vorkonfiguriert.

Sie akzeptiert standardmäßig drei Argumente:

• serviceInformation – Informationen zu Ihrem Azure-Dienst:

  • resourceId – Ressourcen-ID Ihres API Management-Diensts im folgenden Format: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

  • managementApiEndpoint – Azure Management API-Endpunkt (abhängig von Ihrer Umgebung, normalerweise management.azure.com)

• ID Ihres Widgets – Name Ihres Widgets im „PC-freundlichen“ Format (lateinische alphanumerische Kleinbuchstaben und Bindestriche; Contoso widget wird zu contoso-widget). Sie finden sie in package.json unter dem Schlüssel name.

• fallbackConfigPath – Pfad für die lokale Datei config.msapim.json, z. B. ./static/config.msapim.json

@azure/api-management-custom-widgets-tools/getWidgetData

Diese Funktion gibt alle an Ihr benutzerdefiniertes Widget übergebenen Daten aus dem Entwicklerportal zurück. Sie enthält weitere Daten, die beim Debuggen oder in fortgeschritteneren Szenarien nützlich sein können. Diese API wird voraussichtlich mit potenziellen Breaking Changes geändert. Sie gibt ein JSON-Objekt zurück, das die folgenden Schlüssel enthält:

• values – Alle Werte, die Sie im Editor festgelegt haben, dasselbe Objekt, das von getEditorData zurückgegeben wird

• instanceId – ID dieser Instanz des Widgets

Hinzufügen oder Entfernen benutzerdefinierter Eigenschaften

Anhand benutzerdefinierter Eigenschaften können Sie Werte im Code des benutzerdefinierten Widgets über die Verwaltungsbenutzeroberfläche des Entwicklerportals anpassen, ohne den Code zu ändern oder das benutzerdefinierte Widget erneut bereitzustellen. Standardmäßig werden Eingabefelder für vier benutzerdefinierte Eigenschaften definiert. Sie können bei Bedarf weitere benutzerdefinierte Eigenschaften hinzufügen oder entfernen.

So fügen Sie eine benutzerdefinierte Eigenschaft hinzu

1. Fügen Sie in der Datei src/values.tsdem Typ Values den Namen der Eigenschaft und den Typ der Daten hinzu, die darin gespeichert werden.
2. Fügen Sie in derselben Datei einen Standardwert hinzu.
3. Navigieren Sie zur Datei editor.html oder editor/index (der genaue Speicherort hängt von dem von Ihnen ausgewählten Framework ab), und duplizieren Sie eine vorhandene Eingabe, oder fügen Sie selbst eine hinzu.
4. Stellen Sie sicher, dass das Eingabefeld den geänderten Wert an die Funktion onChange meldet, die Sie aus buildOnChange abrufen können.

(Optional) Verwenden eines anderen Frameworks

Um Ihr Widget mithilfe eines anderen JavaScript-UI-Frameworks und der entsprechenden Bibliotheken zu implementieren, müssen Sie das Projekt anhand der folgenden Richtlinien selbst einrichten:

• In den meisten Fällen wird empfohlen, mit der TypeScript-Vorlage zu beginnen.
• Installieren Sie Abhängigkeiten genau wie in jedem anderen npm-Projekt.
• Wenn das Framework Ihrer Wahl nicht mit dem Vite-Buildtool kompatibel ist, konfigurieren Sie es so, dass es kompilierte Dateien im Ordner ./dist ausgibt. Definieren Sie den Speicherort der kompilierten Dateien optional neu, indem Sie einen relativen Pfad als viertes Argument für die Funktion deployNodeJs angeben.
• Für die lokale Entwicklung muss die Datei config.msapim.json an der URL localhost:<port>/config.msapim.json zugänglich sein, wenn der Server ausgeführt wird.

Erstellen von benutzerdefinierten Widgets mit dem Open-Source-React-Komponenten-Toolkit

Das Open-Source-React-Komponenten-Toolkit stellt eine Suite von npm-Paketskripten bereit, mit denen Sie eine React-Anwendung in das benutzerdefinierte Widgetframework konvertieren, testen und das benutzerdefinierte Widget im Entwicklerportal bereitstellen können. Wenn Sie Zugriff auf einen Azure OpenAI-Dienst haben, kann das Toolkit auch ein Widget aus einer von Ihnen bereitgestellten Textbeschreibung erstellen.

Derzeit können Sie das Toolkit auf zwei Arten verwenden, um ein benutzerdefiniertes Widget bereitzustellen:

• Manuell, indem Sie das Toolkit installieren und die npm-Paketskripte lokal ausführen. Sie führen die Skripts sequenziell aus, um eine React-Komponente als benutzerdefiniertes Widget zu erstellen, zu testen und im Entwicklerportal bereitzustellen.
• Mit einer Azure Developer CLI (azd)-Vorlage für eine End-to-End-Bereitstellung. Die azd-Vorlage stellt eine Azure API Management-Instanz und eine Azure OpenAI-Instanz bereit. Nachdem Ressourcen bereitgestellt wurden, hilft Ihnen ein interaktives Skript beim Erstellen, Testen und Bereitstellen eines benutzerdefinierten Widgets im Entwicklerportal anhand einer von Ihnen angegebenen Beschreibung.

Zugehöriger Inhalt

Weitere Informationen zum Entwicklerportal:

• Übersicht über das Azure API Management-Entwicklerportal
• Häufig gestellte Fragen
• Gerüsterstellung eines benutzerdefinierten Widgets für das Entwicklerportal des Azure API Management-Diensts
• Tools zum Arbeiten mit benutzerdefinierten Widgets im Entwicklerportal des Azure API Management-Diensts