Übersicht über das Entwicklerportal

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

Das API Management-Entwicklerportal ist eine automatisch generierte, vollständig anpassbare Website mit der Dokumentation Ihrer APIs. Dort können API-Consumer Ihre APIs entdecken, erfahren, wie sie verwendet werden, Zugriff anfordern und die APIs ausprobieren.

In diesem Artikel werden Features des Entwicklerportals, die vom Portal dargestellten Inhaltstypen sowie Optionen zum Verwalten und Erweitern des Entwicklerportals für Ihre spezifischen Benutzer und Szenarien vorgestellt.

Architekturkonzepte des Entwicklerportals

Die Portalkomponenten können logisch in zwei Kategorien unterteilt werden: Code und Inhalt.

Programmcode

Code wird im GitHub-Repository des API Management-Entwicklerportals verwaltet und umfasst:

• Widgets – stellen visuelle Elemente dar und kombinieren HTML, JavaScript, Stilfähigkeit, Einstellungen und Inhaltszuordnung. Beispiele hierfür sind ein Bild, ein Textabsatz, ein Formular, eine Liste mit APIs usw.
• Formatdefinitionen – Angeben, wie Widgets formatiert werden können
• Modul – das statische Webseiten aus Portalinhalten generiert und in JavaScript geschrieben wird
• Visueller Editor – ermöglicht Anpassungen und das Erstellen von Inhalten im Browser

Inhalt

Der Inhalt ist in zwei Unterkategorien unterteilt: Portalinhalts- und API-Verwaltungsdaten.

• Portalinhalte sind für die Portalwebsite spezifisch und umfassen:

  • Seiten – z. B. Startseite, API-Lernprogramme, Blogbeiträge

  • Medien – Bilder, Animationen und andere dateibasierte Inhalte

  • Layouts – Vorlagen, die mit einer URL übereinstimmen und definieren, wie Seiten angezeigt werden

  • Formatvorlagen – Werte für Formatierungsdefinitionen, z. B. Schriftarten, Farben, Rahmen

  • Einstellungen – Konfigurationen wie favicon, Websitemetadaten

    Portalinhalte (mit Ausnahme von Medien) werden als JSON-Dokumente ausgedrückt.

• API-Verwaltungsdaten umfassen Entitäten wie APIs, Vorgänge, Produkte und Abonnements, die in Ihrer API-Verwaltungsinstanz verwaltet werden.

Anpassen und Formatieren des Portals

Das Entwicklerportal ist sofort einsatzbereit: Es ist bereits mit Ihren veröffentlichten APIs und Produkten gefüllt und kann direkt Ihren Anforderungen entsprechend angepasst werden. Als API-Herausgeber verwenden Sie die Verwaltungsschnittstelle des Entwicklerportals, um die Darstellung und Funktionalität des Entwicklerportals anzupassen.

Wenn Sie zum ersten Mal auf das Portal zugreifen, enthält das Portal Platzhalter für Seiten, Inhalte und Navigationsmenüs. Der angezeigte Platzhalterinhalt ist dafür konzipiert, die Funktionen des Portals zu veranschaulichen und den Anpassungsaufwand zu minimieren, der für die Personalisierung des Portals erforderlich ist.

Eine schrittweise exemplarische Vorgehensweise zum Anpassen und Veröffentlichen des Entwicklerportals finden Sie unter Lernprogramm: Zugreifen und Anpassen des Entwicklerportals.

Visueller Editor

Die Verwaltungsschnittstelle des Entwicklerportals bietet einen visuellen Editor für Herausgeber, um Inhalt und Gestaltung des Portals anzupassen. Mit dem visuellen Editor können Sie Seiten, Abschnitte und Widgets hinzufügen, entfernen und neu anordnen. Sie können auch die Formatierung der Portalelemente ändern, z. B. Schriftarten, Farben und Abstände.

Als Administrator können Sie den Inhalt des Portals mithilfe des visuellen Editors anpassen.

• Verwenden Sie die Menüoptionen auf der linken Seite um Seiten, Medien, Layouts, Menüs, Formatvorlagen oder Websiteeinstellungen zu erstellen oder zu ändern.

• Wechseln Sie oben zwischen Viewports (für Bildschirme unterschiedlicher Größen) oder zeigen Sie die Elemente des Portals an, die für Benutzer in verschiedenen Gruppen sichtbar sind. Zeigen Sie beispielsweise bestimmte Seiten nur für Gruppen an, die bestimmten Produkten zugeordnet sind, oder für Benutzer, die auf bestimmte APIs zugreifen können.

• Außerdem können Sie Änderungen speichern oder rückgängig machen oder die Website veröffentlichen.

• Wählen Sie vorhandene Text- und Überschriftenelemente zum Bearbeiten und Formatieren von Inhalten aus.

• Fügen Sie einer Seite einen Abschnitt hinzu, indem Sie mit dem Mauszeiger auf einen leeren Bereich zeigen und dann auf das blaue Symbol mit dem Pluszeichen klicken. Sie können zwischen mehreren Abschnittslayouts wählen.

  

• Fügen Sie ein Widget (z. B. Text, Bild, benutzerdefiniertes Widget oder API-Liste) hinzu, indem Sie auf einen leeren Bereich zeigen und dann auf das graue Symbol mit dem Pluszeichen klicken.

  

• Ordnen Sie Elemente auf einer Seite per Drag & Drop neu an.

Seiten und Layouts

Der vorab bereitgestellte Inhalt im Entwicklerportal zeigt Seiten mit häufig verwendeten Features. Suchen Sie sie im Bereich "Seiten ". Sie können den Inhalt dieser Seiten ändern oder neue hinzufügen, die Ihren Anforderungen entsprechen.

Wählen Sie " Layouts " im Bereich "Seiten " aus, um zu definieren, wie Seiten angezeigt werden. Das Entwicklerportal verfügt über ein Standardlayout, das auf die Seiten angewendet wird. Sie können dieses Layout ändern und weitere Layouts für Ihre Anforderungen hinzufügen.

Ein Layout wird auf eine Seite angewendet, indem die zugehörige URL-Vorlage mit der URL der Seite abgeglichen wird. Beispielsweise wird ein Layout mit einer URL-Vorlage vom Typ /wiki/* auf jede Seite mit dem Segment /wiki/ in der URL angewendet: /wiki/getting-started, /wiki/styles usw.

In der folgenden Abbildung ist der Inhalt, der zum Layout gehört, blau umrandet, der seitenspezifische Inhalt hingegen ist rot hervorgehoben.

Stilarten

Der Stil-Bereich wird im Hinblick auf Designer entworfen. Verwenden Sie Formatvorlagen, um alle visuellen Elemente in Ihrem Portal zu verwalten und anzupassen, z. B. die in Überschriften und Menüs verwendeten Schriftarten und die Schaltflächenfarben. Die Gestaltung erfolgt hierarchisch: Viele Elemente erben Eigenschaften von anderen Elementen. Ein Beispiel: Schaltflächenelemente verwenden Farben für Text und Hintergrund. Um die Farbe einer Schaltfläche zu ändern, müssen Sie die ursprüngliche Farbvariante ändern.

Um eine Variante zu bearbeiten, wählen Sie sie aus und wählen Sie Stil bearbeiten in den Optionen aus, die darüber angezeigt werden. Schließen Sie das Popupfenster, nachdem Sie darin die gewünschten Änderungen vorgenommen haben.

Erweitern der Portalfunktionalität

In einigen Fällen benötigen Sie möglicherweise Funktionen, die über die im verwalteten Entwicklerportal bereitgestellten Anpassungs- und Formatierungsoptionen hinausgehen. Wenn Sie benutzerdefinierte Logik implementieren müssen, die nicht sofort unterstützt wird, haben Sie mehrere Optionen:

• Fügen Sie benutzerdefinierten HTML-Code direkt über ein Entwicklerportal-Widget hinzu, das für kleine Anpassungen entwickelt wurde , z. B. HTML für ein Formular hinzufügen oder einen Videoplayer einbetten. Der benutzerdefinierte Code wird in einem Inlineframe (IFrame) gerendert.
• Erstellen und hochladen Sie ein benutzerdefiniertes Widget , um komplexere benutzerdefinierte Portalfeatures zu entwickeln und hinzuzufügen.
• Hosten Sie das Portal selbst, nur wenn Sie Änderungen am Kern der Codebasis des Entwicklerportals vornehmen müssen. Für diese Option ist eine erweiterte Konfiguration erforderlich. Die Unterstützung durch den Azure-Support ist auf die grundlegende Einrichtung selbstgehosteter Portale beschränkt.

Steuern des Zugriffs auf Portalinhalte

Das Entwicklerportal wird mit Ihrer API Management-Instanz synchronisiert, um Inhalte wie APIs, Vorgänge, Produkte, Abonnements und Benutzerprofile anzuzeigen. APIs und Produkte müssen im Entwicklerportal in einem veröffentlichten Zustand angezeigt werden.

Inhaltssichtbarkeit und -zugriff

In der API-Verwaltung werden Benutzergruppen verwendet, um die Sichtbarkeit von Produkten und ihren zugehörigen APIs für Entwickler zu verwalten. Zusätzlich zur Verwendung integrierter Gruppen können Sie benutzerdefinierte Gruppen erstellen, die Ihren Anforderungen entsprechen. Produkte gewähren Sichtbarkeit für Gruppen, und Entwickler können alle Produkte anzeigen und abonnieren, die für die Gruppen sichtbar sind, in denen sie Mitglied sind.

Sie können auch steuern, wie andere Portalinhalte (z. B. Seiten und Abschnitte) für unterschiedliche Benutzer je nach ihrer Identität angezeigt werden. Beispielsweise können Sie gewisse Seiten nur für Benutzer anzeigen, die Zugriff auf ein bestimmtes Produkt oder eine bestimmte API haben. Sie können auch festlegen, dass ein Abschnitt einer Seite nur für bestimmte Benutzergruppen angezeigt wird. Das Entwicklerportal verfügt über integrierte Steuerungen für diese Anforderungen.

• Wenn Sie eine Seite hinzufügen oder die Einstellungen einer vorhandenen Seite bearbeiten, treffen Sie unter Access eine Auswahl, um die Benutzer oder Gruppen zu steuern, die die Seite sehen können.

  

  Tipp

  Um die Einstellungen einer vorhandenen Seite zu bearbeiten, wählen Sie das Zahnradsymbol neben dem Seitennamen auf der Registerkarte "Seiten " aus.

• Wenn Sie Seiteninhalte wie einen Seitenabschnitt, ein Menü oder eine Schaltfläche zum Bearbeiten auswählen, wählen Sie das Symbol "Zugriff ändern " aus, um die Benutzer oder Gruppen zu steuern, die das Element auf der Seite sehen können.

  

  • Sie können die Sichtbarkeit der folgenden Seiteninhalte ändern: Abschnitte, Menüs, Schaltflächen und Anmeldung für die OAuth-Autorisierung.

  • Mediendateien wie Bilder auf einer Seite erben die Sichtbarkeit der Elemente, die sie enthalten.

Wenn ein Benutzer das Entwicklerportal mit angewendeten Sichtbarkeits- und Zugriffssteuerungen besucht:

• Das Entwicklerportal blendet automatisch Schaltflächen oder Navigationselemente aus, die auf Seiten verweisen, auf die ein Benutzer keinen Zugriff hat.

• Ein Versuch eines Benutzers, auf eine Seite zuzugreifen, für die er nicht autorisiert ist, führt zu einem Fehler vom Typ „404: Nicht gefunden“.

Richtlinie für Inhaltssicherheit

Sie können eine Inhaltssicherheitsrichtlinie aktivieren, um Ihrem Entwicklerportal eine zusätzliche Sicherheitsebene hinzuzufügen und bestimmte Arten von Angriffen wie Cross-Site Scripting und Dateneinschleusung zu minimieren. Mit einer Inhaltssicherheitsrichtlinie lädt das Entwicklerportal im Browser nur Ressourcen von vertrauenswürdigen Speicherorten, die Sie angeben, z. B. von Ihrer Unternehmenswebsite oder anderen vertrauenswürdigen Domänen.

So aktivieren Sie eine Inhaltssicherheitsrichtlinie

1. Navigieren Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.
2. Wählen Sie im linken Menü unter "Entwicklerportal" die Option "Portaleinstellungen" aus.
3. Wählen Sie auf der Registerkarte "Inhaltssicherheitsrichtlinie" die Option "Aktiviert" aus.
4. Fügen Sie unter "Zulässige Quellen" einen oder mehrere Hostnamen hinzu, die vertrauenswürdige Speicherorte angeben, aus denen das Entwicklerportal Ressourcen laden kann. Sie können auch ein Platzhalterzeichen angeben, um alle Unterdomänen einer Domäne zuzulassen. Mit *.contoso.com werden beispielsweise alle Unterdomänen von contoso.com zugelassen.
5. Wählen Sie "Speichern" aus.

Interaktive Testkonsole

Das Entwicklerportal enthält auf den API-Referenzseiten eine Funktion zum Ausprobieren, sodass Portalbesucher Ihre APIs direkt über eine interaktive Konsole testen können.

Die Testkonsole unterstützt APIs mit unterschiedlichen Autorisierungsmodellen, z. B. APIs, die keine Autorisierung erfordern, oder APIs, die einen Abonnementschlüssel oder OAuth 2.0-Autorisierung erfordern. Im letzteren Fall können Sie die Testkonsole so konfigurieren, dass ein gültiges OAuth-Token im Auftrag des Testkonsolenbenutzers generiert wird. Weitere Informationen finden Sie unter Autorisieren der Testkonsole des Entwicklerportals durch Konfigurieren der OAuth 2.0-Benutzerautorisierung.

Verwalten der Benutzerregistrierung und -anmeldung

Das Entwicklerportal ermöglicht standardmäßig den anonymen Zugriff. Das bedeutet, dass jeder das Portal und Inhalte darin einsehen kann, ohne sich anzumelden, obwohl Zugriff auf bestimmte Inhalte und Funktionen wie die Verwendung der Testkonsole ggf. eingeschränkt sind. Sie können eine Einstellung für die Entwicklerportalwebsite aktivieren, damit Benutzer sich anmelden müssen, um auf das Portal zuzugreifen.

Das Portal unterstützt mehrere Optionen für die Benutzerregistrierung und -anmeldung:

• Standardauthentifizierung für Entwickler, um sich mit Anmeldeinformationen bei API-Verwaltungs-Benutzerkonten anzumelden. Entwickler können sich direkt über das Portal für ein Konto registrieren, oder Sie können Konten für sie erstellen.

• Beschränken Sie abhängig von Ihren Szenarien den Zugriff auf das Portal, indem Sie Benutzer auffordern, sich mit einem Microsoft Entra ID- oder Microsoft Entra External ID-Konto anzumelden.

• Wenn Sie die Entwickleranmeldung und -anmeldung bereits über eine vorhandene Website verwalten, delegieren Sie die Authentifizierung anstelle der integrierten Authentifizierung des Entwicklerportals.

Erfahren Sie mehr über Optionen zum Sichern der Benutzeranmeldung und -anmeldung beim Entwicklerportal.

Berichte für Benutzer

Das Entwicklerportal generiert Berichte für authentifizierte Benutzer, um ihre individuelle API-Nutzung, Datenübertragung und Antwortzeiten anzuzeigen, einschließlich der aggregierten Nutzung durch bestimmte Produkte und Abonnements. Benutzer können die Berichte anzeigen, indem Sie Berichte im Standardnavigationsmenü für authentifizierte Benutzer auswählen. Benutzer können Berichte nach Zeitintervall filtern. Der Filter kann maximal die letzten 90 Tage umfassen.

Speichern und Veröffentlichen von Websiteinhalten

Nachdem Sie den Inhalt oder die Konfiguration des Entwicklerportals aktualisiert haben, müssen Sie Ihre Änderungen speichern und veröffentlichen, um sie den Portalbesuchern zur Verfügung zu stellen. Das Entwicklerportal verwaltet einen Datensatz der inhalte, die Sie veröffentlicht haben, und Sie können bei Bedarf zu einer vorherigen Portalrevision zurückkehren.

Änderungen speichern

Wenn Sie eine Änderung im Portal vornehmen, müssen Sie sie manuell speichern, indem Sie oben im Menü "Speichern" die Schaltfläche " Speichern " auswählen oder [STRG]+[S] drücken. Bei Bedarf können Sie Ihre zuletzt gespeicherten Änderungen rückgängig machen . Gespeicherte Änderungen sind nur für Sie sichtbar. Portalbesuchern werden sie erst nach der Veröffentlichung angezeigt.

Veröffentlichen des Portals

Um Ihr Portal und die neuesten Änderungen für Besucher verfügbar zu machen, müssen Sie es veröffentlichen . Sie veröffentlichen das Portal über die Verwaltungsschnittstelle des Portals oder über das Azure-Portal.

Veröffentlichen über die Verwaltungsschnittstelle

1. Stellen Sie sicher, dass Sie Ihre Änderungen gespeichert haben, indem Sie auf die Schaltfläche " Speichern " klicken.

2. Wählen Sie oben im Menü " Website veröffentlichen" aus. Dieser Vorgang kann einige Minuten dauern.

   

Veröffentlichen über das Azure-Portal

1. Navigieren Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.

2. Wählen Sie im linken Menü unter "Entwicklerportal" die Option "Portalübersicht" aus.

3. Wählen Sie im Portalübersichtsfensterdie Option "Veröffentlichen" aus.

   

Wiederherstellen einer vorherigen Portalrevision

Jedes Mal, wenn Sie das Entwicklerportal veröffentlichen, wird eine entsprechende Portalrevision gespeichert. Sie können jederzeit eine vorherige Portalrevision erneut veröffentlichen. Sie können beispielsweise ein Rollback für eine Änderung durchführen, die Sie bei der letzten Veröffentlichung des Portals eingeführt haben.

So stellen Sie eine vorherige Portalrevision wieder her

1. Navigieren Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.
2. Wählen Sie im linken Menü unter "Entwicklerportal" die Option "Portalübersicht" aus.
3. Wählen Sie auf der Registerkarte " Überarbeitungen " das Kontextmenü (...) für eine Überarbeitung aus, die Sie wiederherstellen möchten, und wählen Sie dann " Aktuell erstellen" und "Veröffentlichen" aus.

Das Portal zurücksetzen

Wenn Sie alle Änderungen, die Sie am Entwicklerportal vorgenommen haben, verwerfen möchten, können Sie die Website auf den Ausgangszustand zurücksetzen. Durch das Zurücksetzen des Portals werden alle Änderungen gelöscht, die Sie an den Entwicklerportalseiten, Layouts, Anpassungen und hochgeladenen Medien vorgenommen haben.

So setzen Sie das Entwicklerportal zurück

1. Wählen Sie in der Verwaltungsoberfläche links im Menü des visuellen Editors "Einstellungen" aus.
2. Wählen Sie auf der Registerkarte "Erweitert " die Option "Ja" aus, setzen Sie die Website auf den Standardzustand zurück.
3. Wählen Sie "Speichern" aus.

API-Verwaltungs- und API Center-Portale

Die Azure API Management- und Azure API Center-Dienste bieten sowohl Portale für Entwickler zum Ermitteln und Nutzen von APIs:

• Das API Management-Entwicklerportal ermöglicht Es Benutzern, verwaltete APIs zu finden, zu erfahren, wie Sie sie verwenden, Zugriff anfordern und testen können.
• Das API Center-Portal (Vorschau) ist ein Portal mit mehreren Gateways, in dem Benutzer das vollständige API-Inventar der Organisation ermitteln und filtern können.

Während die beiden Portale einige Features teilen, weisen sie auch unterschiedliche Unterschiede auf. In der folgenden Tabelle werden die aktuellen Funktionen verglichen, um zu bestimmen, welches Portal verwendet werden soll. Einige Organisationen bevorzugen möglicherweise ein Portal, während andere beides benötigen.

¹ Das API Center-Portal kann alle APIs in Ihrer Organisation enthalten, einschließlich der apIs, die in Azure API Management und anderen Plattformen verwaltet werden, sowie nicht verwaltete APIs und APIs in der Entwicklung.

Zugehöriger Inhalt

Weitere Informationen zum Entwicklerportal:

• Zugreifen und Anpassen des verwalteten Entwicklerportals
• Erweitern der Funktionalität des verwalteten Entwicklerportals
• Aktivieren der Protokollierung der Nutzung des Entwicklerportals
• Einrichten einer selbst gehosteten Version des Portals

Weitere Ressourcen:

• GitHub-Repository mit dem Quellcode
• Häufig gestellte Fragen zum Entwicklerportal