Übersicht über das EntwicklerportalOverview of the developer portal

Das Entwicklerportal ist eine automatisch generierte, vollständig anpassbare Website mit der Dokumentation Ihrer APIs.Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. Dort können API-Consumer ihre APIs ermitteln, erfahren, wie sie verwendet werden, Zugriff anfordern und die APIs ausprobieren.It is where API consumers can discover your APIs, learn how to use them, request access, and try them out.

In diesem Artikel werden die Unterschiede zwischen selbstgehosteten und verwalteten Versionen des Entwicklerportals in API Management beschrieben.This article describes the differences between self-hosted and managed versions of the developer portal in API Management. Außerdem erhalten Sie hier Antworten auf häufig gestellte Fragen.It also provides answers to frequently asked questions.

Entwicklerportal für API Management

VerfügbarkeitAvailability

Wichtig

Diese Funktion ist auf den Ebenen Premium und Standard, Basic und Entwickler von API Management verfügbar.This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

Migration vom LegacyportalMigration from the legacy portal

Wichtig

Das Legacyentwicklerportal ist mittlerweile veraltet, und es werden nur noch Sicherheitsupdates angewendet.The legacy developer portal is now deprecated and it will receive security updates only. Sie können die Anwendung bis Oktober 2023 wie gewohnt weiterhin verwenden, daraufhin wird sie aus allen API Management-Diensten entfernt.You can continue to use it, as per usual, until its retirement in October 2023, when it will be removed from all API Management services.

Die Migration zum neuen Entwicklerportal ist in einem eigenen Artikel in der Dokumentation beschrieben.Migration to the new developer portal is described in the dedicated documentation article.

Anpassung und FormatierungCustomization and styling

Das Entwicklerportal kann mit dem integrierten, visuellen Drag & Drop-Editor angepasst und formatiert werden.The developer portal can be customized and styled through the built-in, drag-and-drop visual editor. Weitere Einzelheiten finden Sie in diesem Tutorial.See this tutorial for more details.

ErweiterbarkeitExtensibility

Der API Management-Dienst umfasst ein integriertes verwaltetes Entwicklerportal, das laufend aktualisiert wird.Your API Management service includes a built-in, always up-to-date, managed developer portal. Sie können über die Benutzeroberfläche des Azure-Portals darauf zugreifen.You can access it from the Azure portal interface.

Wenn Sie es mit benutzerdefinierter Logik erweitern müssen, was standardmäßig nicht unterstützt wird, können Sie die entsprechende Codebasis ändern.If you need to extend it with custom logic, which isn't supported out-of-the-box, you can modify its codebase. Die Codebasis des Portals ist in einem GitHub-Repository verfügbar.The portal's codebase is available in a GitHub repository. Beispielsweise können Sie ein neues Widget implementieren, das in das Supportsystem eines Drittanbieters integriert ist.For example, you could implement a new widget, which integrates with a third-party support system. Wenn Sie neue Funktionen implementieren, können Sie aus folgenden Optionen wählen:When you implement new functionality, you can choose one of the following options:

  • Selbsthosting des resultierenden Portals außerhalb Ihres API Management-Diensts.Self-host the resulting portal outside of your API Management service. Wenn Sie das Portal selbst hosten, sind Sie der Maintainer und selbst für dessen Upgrades verantwortlich.When you self-host the portal, you become its maintainer and you are responsible for its upgrades. Die Unterstützung durch den Azure-Support ist nur auf die grundlegende Einrichtung selbst gehosteter Portale beschränkt, wie im Bereich „Wiki“ des Repositorys dokumentiert.Azure Support's assistance is limited only to the basic setup of self-hosted portals, as documented in the Wiki section of the repository.
  • Öffnen Sie einen Pull Request, damit das API Management-Team neue Funktionen mit der Codebasis des verwalteten Portals zusammenführen kann.Open a pull request for the API Management team to merge new functionality to the managed portal's codebase.

Details und Anweisungen zur Erweiterbarkeit finden Sie im GitHub-Repository und im Tutorial zum Implementieren eines Widgets.For extensibility details and instructions, refer to the GitHub repository and the tutorials on implementing a widget. Das Tutorial zum Anpassen des verwalteten Portals führt Sie schrittweise durch den Verwaltungsbereich des Portals, der sowohl in der verwalteten als auch in der selbstgehosteten Version vorhanden ist.The tutorial for customizing the managed portal walks you through the portal's administrative panel, which is common for managed and self-hosted versions.

Häufig gestellte FragenFrequently asked questions

In diesem Abschnitt beantworten wir häufig gestellte Fragen zum Entwicklerportal, die allgemeiner Natur sind.In this section, we answer common questions about the developer portal, which are of general nature. Fragen, die sich speziell auf die selbstgehostete Version beziehen, finden Sie im GitHub-Repository im Abschnitt „Wiki“.For questions specific to the self-hosted version, refer to the wiki section of the GitHub repository.

Wie kann ich von der Vorschauversion des Portals migrieren?How can I migrate from the preview version of the portal?

Beim ersten Starten der Vorschauversion des Entwicklerportals haben Sie die Vorschauversion des Standardinhalts in Ihrem API Management-Dienst bereitgestellt.When you first launched the preview version of developer portal, you provisioned the preview version of its default content in your API Management service. In der allgemein verfügbaren Version wurde der Standardinhalt erheblich geändert.The default content has been significantly modified in the generally available version. So enthält die Vorschauversion des Standardinhalts beispielsweise auf der Anmeldeseite keine OAuth-Schaltflächen, sie verwendet zur Anzeige von APIs andere Widgets, und die Strukturierung der Seiten im Entwicklerportal wird mit eingeschränkten Funktionen ausgeführt.For example, the preview version of default content doesn't include OAuth buttons in the log-in pages, it uses different widgets for displaying APIs, and relies on limited capabilities for structuring developer portal pages. Trotz der inhaltlichen Unterschiede wird die Engine des Portals (samt der zugrunde liegenden Widgets) bei jeder Veröffentlichung des Entwicklerportals automatisch aktualisiert.Even though there are differences in the content, the portal's engine (including underlying widgets) is automatically updated every time you publish your developer portal.

Wenn Sie Ihr Portal basierend auf der Vorschauversion des Inhalts umfangreich angepasst haben, können Sie es unverändert weiter verwenden und neue Widgets manuell auf den Seiten des Portals platzieren.If you heavily customized your portal based on the preview version of content, you may continue to use it as is and place new widgets manually on portal's pages. Andernfalls wird empfohlen, den Inhalt Ihres Portals durch den neuen Standardinhalt zu ersetzen.Otherwise, we recommend replacing your portal's content with the new default content.

Wenn Sie den Inhalt in einem verwalteten Portal zurücksetzen möchten, wählen Sie im Menüabschnitt Vorgänge die Option Inhalt zurücksetzen aus.To reset the content in a managed portal, select Reset content in the Operations menu section. Dadurch wird der gesamte Inhalt des Portals entfernt, und die neuen Standardinhalte werden bereitgestellt.This operation will remove all the content of the portal and provision new default content. Alle Anpassungen und Änderungen des Entwicklerportals gehen dabei verloren.You will lose all developer portal customizations and changes. Dieser Vorgang kann nicht rückgängig gemacht werden.You can't undo this action.

Zurücksetzen des Portalinhalts

Wenn Sie die selbstgehostete Version verwenden, führen Sie die Skripts scripts.v2/cleanup.bat und scripts.v2/generate.bat aus dem GitHub-Repository aus, um vorhandene Inhalte zu entfernen und neue Inhalte bereitzustellen.If you're using the self-hosted version, run scripts.v2/cleanup.bat and scripts.v2/generate.bat scripts from the GitHub repository to remove existing content and provision new content. Stellen Sie sicher, dass Sie im Vorfeld den Code Ihres Portals im GitHub-Repository auf die neueste Version aktualisieren.Make sure to upgrade your portal's code to the latest release from the GitHub repository beforehand.

Wenn Sie zum ersten Mal nach der Ankündigung der allgemeinen Verfügbarkeit im November 2019 auf das Portal zugegriffen haben, sollte der neue Standardinhalt bereits vorhanden sein. In diesem Fall ist keine weitere Aktion erforderlich.If you first accessed the portal after the general availability announcement in November 2019, it should already feature the new default content and no further action is required.

Eine von mir benötigte Funktion wird im Portal nicht unterstütztFunctionality I need isn't supported in the portal

Sie können im GitHub-Repository eine Funktionsanforderung öffnen oder die fehlende Funktionalität selbst implementieren.You can open a feature request in the GitHub repository or implement the missing functionality yourself. Weitere Informationen finden Sie im Abschnitt Erweiterbarkeit.See the Extensibility section above for more details.

Wie kann ich Portalbereitstellungen automatisieren?How can I automate portal deployments?

Sie können über die REST-API programmgesteuert auf die Inhalte des Entwicklerportals zugreifen und diese verwalten, und zwar unabhängig davon, ob Sie eine verwaltete oder eine selbstgehostete Version verwenden.You can programmatically access and manage the developer portal's content through the REST API, regardless if you're using a managed or a self-hosted version.

Die APIs sind im Wiki-Abschnitt des GitHub-Repositorys dokumentiert.The API is documented in the GitHub repository's wiki section. Diese Dokumentation kann für die Automatisierung von Migrationen von Portalinhalten zwischen Umgebungen verwendet werden (z. B. aus einer Testumgebung in die Produktionsumgebung).It can be used for automating migrations of portal content between environments - for example, from a test environment to the production environment. Weitere Informationen zu diesem Vorgang finden Sie in diesem Dokumentationsartikel auf GitHub.You can learn more about this process in this documentation article on GitHub.

Wie kann ich von der verwalteten Version zur selbstgehosteten Version wechseln?How do I move from the managed to the self-hosted version?

Informationen finden Sie im ausführlichen Artikel im Bereich „Wiki“ des Entwicklerportal-Repositorys auf GitHub.See the detailed article in the Wiki section of the developer portal repository on GitHub.

Kann ich über mehrere Entwicklerportale in einem API Management-Dienst verfügen?Can I have multiple developer portals in one API Management service?

Sie können über ein verwaltetes Portal und mehrere selbstgehostete Portale verfügen.You can have one managed portal and multiple self-hosted portals. Der Inhalt aller Portale wird in demselben API Management-Dienst gespeichert, sodass die Portale identisch sind.The content of all portals is stored in the same API Management service, so they will be identical. Wenn das Aussehen und die Funktionalität der einzelnen Portale unterschiedlich sein soll, können Sie diese eigenständig mit Ihren benutzerdefinierten Widgets hosten, die Seiten zur Runtime dynamisch anpassen, beispielsweise basierend auf der URL.If you want to differentiate portals' appearance and functionality, you can self-host them with your own custom widgets that dynamically customize pages on runtime, for example based on the URL.

Unterstützt das Portal Azure Resource Manager-Vorlagen und/oder ist es mit dem API Management DevOps Resource Kit kompatibel?Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?

Nein.No.

Wird der Inhalt des Portals mit der Sicherungs-/Wiederherstellungsfunktion in API Management gespeichert?Is the portal's content saved with the backup/restore functionality in API Management?

Nein.No.

Muss ich zusätzliche VNET-Konnektivität für die Abhängigkeiten des verwalteten Portals aktivieren?Do I need to enable additional VNet connectivity for the managed portal dependencies?

In den meisten Fällen nicht.In most cases - no.

Wenn sich Ihr API Management-Dienst in einem internen VNET befindet, kann nur innerhalb des Netzwerks auf Ihr Entwicklerportal zugegriffen werden.If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. Der Hostname des Verwaltungsendpunkts muss über den Computer, mit dem Sie auf die Verwaltungsschnittstelle des Portals zugreifen, zur internen VIP des Diensts aufgelöst werden.The management endpoint's host name must resolve to the internal VIP of the service from the machine you use to access the portal's administrative interface. Vergewissern Sie sich, dass der Verwaltungsendpunkt im DNS registriert ist.Make sure the management endpoint is registered in the DNS. Ist die Konfiguration fehlerhaft, wird ein Fehler angezeigt: Unable to start the portal. See if settings are specified correctly in the configuration (...).In case of misconfiguration, you will see an error: Unable to start the portal. See if settings are specified correctly in the configuration (...).

Wenn sich Ihr API Management-Dienst in einem internen VNET befindet und Sie über Application Gateway über das Internet darauf zugreifen, stellen Sie sicher, dass Sie die Konnektivität mit dem Entwicklerportal und den Verwaltungsendpunkten von API Management aktivieren.If your API Management service is in an internal VNet and you're accessing it through Application Gateway from the Internet, make sure to enable connectivity to the developer portal and the management endpoints of API Management. Möglicherweise müssen Sie die Firewallregeln für Webanwendungen deaktivieren.You may need to disable Web Application Firewall rules. Weitere Informationen finden Sie in diesem Dokumentationsartikel.See this documentation article for more details.

Ich habe eine benutzerdefinierte API Management-Domäne zugewiesen, und das veröffentlichte Portal funktioniert nicht.I have assigned a custom API Management domain and the published portal doesn't work

Nachdem Sie die Domäne aktualisiert haben, müssen Sie das Portal erneut veröffentlichen, damit die Änderungen wirksam werden.After you update the domain, you need to republish the portal for the changes to take effect.

Ich habe einen Identitätsanbieter hinzugefügt, er wird im Portal aber nicht angezeigt.I have added an identity provider and I can't see it in the portal

Nachdem Sie einen Identitätsanbieter (beispielsweise Azure AD oder Azure AD B2C) konfiguriert haben, müssen Sie das Portal erneut veröffentlichen, damit die Änderungen wirksam werden.After you configure an identity provider (for example, Azure AD, Azure AD B2C), you need to republish the portal for the changes to take effect. Stellen Sie sicher, dass die Seiten des Entwicklerportals das OAuth-Schaltflächen-Widget enthalten.Make sure your developer portal pages include the OAuth buttons widget.

Ich habe die Delegierung eingerichtet, sie wird vom Portal aber nicht verwendet.I have set up delegation and the portal doesn't use it

Nachdem Sie die Delegierung eingerichtet haben, müssen Sie das Portal erneut veröffentlichen, damit die Änderungen wirksam werden.After you set up delegation, you need to republish the portal for the changes to take effect.

Meine anderen API Management-Konfigurationsänderungen wurden nicht an das Entwicklerportal weitergegeben.My other API Management configuration changes haven't been propagated in the developer portal

Bei den meisten Konfigurationsänderungen (beispielsweise für das VNET, für die Anmeldung und für Produktbedingungen) ist eine erneute Veröffentlichung des Portals erforderlich.Most configuration changes (for example, VNet, sign-in, product terms) require republishing the portal.

Beim Verwenden der interaktiven Konsole erhalte ich einen CORS-Fehler.I'm getting a CORS error when using the interactive console

Die interaktive Konsole sendet eine clientseitige API-Anforderung über den Browser.The interactive console makes a client-side API request from the browser. Beheben Sie das CORS-Problem, indem Sie eine CORS-Richtlinie für Ihre API(s) hinzufügen.Resolve the CORS problem by adding a CORS policy on your API(s).

Sie können den Status der CORS-Richtlinie im Abschnitt Portalübersicht Ihres API Management-Diensts im Azure-Portal überprüfen.You can check the status of the CORS policy in the Portal overview section of your API Management service in the Azure portal. Ein Warnfeld zeigt eine fehlende oder falsch konfigurierte Richtlinie an.A warning box indicates an absent or misconfigured policy.

Screenshot, der zeigt, wo Sie den Status Ihrer CORS-Richtlinie überprüfen können.

Wenden Sie die COLRS-Richtlinie automatisch an, indem Sie auf die Schaltfläche CORS aktivieren klicken.Automatically apply the CORS policy by clicking on the Enable CORS button.

Sie können CORS auch manuell aktivieren.You can also enable CORS manually.

  1. Wählen Sie den Link Manuelle Anwendung auf globaler Ebene aus, um den generierten Richtliniencode anzuzeigen.Select the Manually apply it on the global level link to see the generated policy code.
  2. Navigieren Sie im Azure-Portal im Abschnitt APIs Ihres API Management-Diensts zu Alle APIs.Navigate to All APIs in the APIs section of your API Management service in the Azure portal.
  3. Wählen Sie im Abschnitt Eingehende Verarbeitung das Symbol </> aus.Select the </> icon in the Inbound processing section.
  4. Fügen Sie die Richtlinie in den Abschnitt der XML-Datei ein.Insert the policy in the section of the XML file. Stellen Sie sicher, dass der -Wert mit der Domäne Ihres Entwicklerportals übereinstimmt.Make sure the value matches your developer portal's domain.

Hinweis

Wenn Sie die CORS-Richtlinie nicht im API-Bereich, sondern im Produktbereich anwenden und Ihre API die Abonnementschlüsselauthentifizierung über einen Header verwendet, funktioniert Ihre Konsole nicht.If you apply the CORS policy in the Product scope, instead of the API(s) scope, and your API uses subscription key authentication through a header, your console won't work.

Der Browser gibt automatisch eine HTTP-Anforderung vom Typ „OPTIONS“ aus, die keinen Header mit dem Abonnementschlüssel enthält.The browser automatically issues an OPTIONS HTTP request, which doesn't contain a header with the subscription key. Aufgrund des fehlenden Abonnementschlüssels kann API Management den OPTIONS-Aufruf keinem Produkt zuordnen und somit die CORS-Richtlinie nicht anwenden.Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can't apply the CORS policy.

Zur Umgehung dieses Problems können Sie den Abonnementschlüssel in einem Abfrageparameter übergeben.As a workaround you can pass the subscription key in a query parameter.

Hinweis

Es wird nur eine CORS-Richtlinie ausgeführt.Only one CORS policy is executed. Wenn Sie mehrere CORS-Richtlinien angegeben haben (z. B. auf API-Ebene und auf der Ebene alle APIs), funktioniert Ihre interaktive Konsole möglicherweise nicht wie erwartet.If you specified multiple CORS policies (for example, on the API level and on the all-APIs level), your interactive console may not work as expected.

Welche Berechtigungen sind zum Bearbeiten des Entwicklerportals erforderlich?What permissions do I need to edit the developer portal?

Sollte beim Öffnen des Portals im Verwaltungsmodus der Fehler Oops. Something went wrong. Please try again later. angezeigt werden, verfügen Sie möglicherweise nicht über die erforderlichen Berechtigungen (Azure RBAC).If you're seeing the Oops. Something went wrong. Please try again later. error when you open the portal in the administrative mode, you may be lacking the required permissions (Azure RBAC).

Bei den Legacyportalen war die Berechtigung Microsoft.ApiManagement/service/getssotoken/action im Dienstbereich (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) erforderlich, um dem Benutzer Administratorzugriff auf die Portale zu gewähren.The legacy portals required the permission Microsoft.ApiManagement/service/getssotoken/action at the service scope (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) to allow the user administrator access to the portals. Für das neue Portal ist die Berechtigung Microsoft.ApiManagement/service/users/token/action im Bereich /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1 erforderlich.The new portal requires the permission Microsoft.ApiManagement/service/users/token/action at the scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.

Sie können das folgende PowerShell-Skript verwenden, um eine Rolle mit der erforderlichen Berechtigung zu erstellen.You can use the following PowerShell script to create a role with the required permission. Vergessen Sie nicht, den Parameter <subscription-id> zu ändern.Remember to change the <subscription-id> parameter.

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount 
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor" 
$customRole = $contributorRole 
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin" 
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator" 
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action" 
$customRole.IsCustom = $true 
$customRole.AssignableScopes.Clear() 
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>') 
New-AzRoleDefinition -Role $customRole 

Nachdem die Rolle erstellt wurde, kann sie im Azure-Portal im Abschnitt Zugriffssteuerung (IAM) einem beliebigen Benutzer zugewiesen werden.Once the role is created, it can be granted to any user from the Access Control (IAM) section in the Azure portal. Wenn Sie diese Rolle einem Benutzer zuweisen, wird die Berechtigung im Dienstbereich zugewiesen.Assigning this role to a user will assign the permission at the service scope. Der Benutzer kann SAS-Token im Namen jedes beliebigen Benutzers im Dienst generieren.The user will be able to generate SAS tokens on behalf of any user in the service. Diese Rolle muss mindestens dem Administrator des Diensts zugewiesen werden.At the minimum, this role needs to be assigned to the administrator of the service. Der folgende PowerShell-Befehl zeigt, wie Sie die Rolle dem Benutzer user1 im kleinstmöglichen Bereich zuweisen, um dem Benutzer keine unnötigen Berechtigungen zu erteilen:The following PowerShell command demonstrates how to assign the role to a user user1 at the lowest scope to avoid granting unnecessary permissions to the user:

New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1" 

Nach Erteilung der Berechtigungen muss sich der betreffende Benutzer abmelden und erneut beim Azure-Portal anmelden, damit die neuen Berechtigungen wirksam werden.After the permissions have been granted to a user, the user must sign out and sign in again to the Azure portal for the new permissions to take effect.

Der Fehler Unable to start the portal. See if settings are specified correctly (...) wird angezeigt.I'm seeing the Unable to start the portal. See if settings are specified correctly (...) error

Dieser Fehler wird angezeigt, wenn ein Aufruf vom Typ GET für https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview nicht erfolgreich war.This error is shown when a GET call to https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview fails. Der Aufruf wird vom Browser über die Verwaltungsschnittstelle des Portals ausgegeben.The call is issued from the browser by the administrative interface of the portal.

Wenn sich Ihr API Management-Dienst in einem VNET befindet, lesen Sie weiter oben die Frage zur VNET-Konnektivität.If your API Management service is in a VNet - refer to the VNet connectivity question above.

Der Aufruffehler kann auch auf ein TLS/SSL-Zertifikat zurückzuführen sein, das einer benutzerdefinierten Domäne zugewiesen ist und dem der Browser nicht vertraut.The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. Sie können die benutzerdefinierte Domäne des Verwaltungsendpunkts entfernen. API Management greift daraufhin auf den Standardendpunkt mit einem vertrauenswürdigen Zertifikat zurück.As a mitigation, you can remove the management endpoint custom domain - API Management will fall back to the default endpoint with a trusted certificate.

Was ist die Browserunterstützung für das Portal?What's the browser support for the portal?

BrowserBrowser UnterstütztSupported
Apple SafariApple Safari Ja1Yes1
Google ChromeGoogle Chrome Ja1Yes1
Microsoft EdgeMicrosoft Edge Ja1Yes1
Microsoft Internet ExplorerMicrosoft Internet Explorer NeinNo
Mozilla FirefoxMozilla Firefox Ja1Yes1

1 In den beiden neuesten Produktionsversionen unterstützt.1 Supported in the two latest production versions.

Nächste SchritteNext steps

Weitere Informationen zum neuen Entwicklerportal:Learn more about the new developer portal:

Weitere Ressourcen:Browse other resources: