Vue d’ensemble du portail des développeurs Gestion des API AzureAzure API Management developer portal overview

Le portail des développeurs est un site web généré automatiquement et entièrement personnalisable avec la documentation de vos API.Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. C’est là que les consommateurs d’API peuvent découvrir vos API, apprendre à les utiliser, y demander l’accès et les essayer.It is where API consumers can discover your APIs, learn how to use them, request access, and try them out.

Cet article décrit les différences entre la version auto-hébergée et la version managée du portail des développeurs dans la Gestion des API.This article describes the differences between self-hosted and managed versions of the developer portal in API Management. Il explique également son architecture et répond aux questions fréquentes.It also explains its architecture and provides answers to frequently asked questions.

Portail des développeurs Gestion des API

DisponibilitéAvailability

Important

Cette fonctionnalité est disponible dans les niveaux Premium, Standard, De base et Développeur de Gestion des API.This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

Version managée et version auto-hébergéeManaged and self-hosted versions

Vous pouvez générer votre portail des développeurs de deux manières :You can build your developer portal in two ways:

  • Version managée, via la modification et la personnalisation du portail : intégrée dans votre instance de Gestion des API et accessible via l’URL <your-api-management-instance-name>.developer.azure-api.net ;Managed version - by editing and customizing the portal, which is built into your API Management instance and is accessible through the URL <your-api-management-instance-name>.developer.azure-api.net. Pour savoir comment accéder au portail managé et le personnaliser, voir cet article de documentation.Refer to this documentation article to learn how to access and customize the managed portal.
  • version auto-hébergée, via le déploiement et l’auto-hébergement de votre portail en dehors d’une instance de gestion des API.Self-hosted version - by deploying and self-hosting your portal outside of an API Management instance. Cette approche vous permet de modifier la base de code du portail et d’étendre la fonctionnalité principale fournie.This approach allows you to edit the portal's codebase and extend the provided core functionality. Vous devez également passer à la dernière version du portail par vous-même.You also need to upgrade the portal to the latest version yourself. Pour obtenir plus de détails et d’instructions, reportez-vous au dépôt GitHub avec le code source du portail et au tutoriel sur l’implémentation d’un widget.For details and instructions, refer to the GitHub repository with the source code of the portal and the tutorial on implementing a widget. Le tutoriel de la version managée décrit le panneau d’administration du portail, qui est également proposé dans la version auto-hébergée.The tutorial for the managed version walks through the portal's administrative panel, which is also featured in the self-hosted version.

Concepts architecturaux du portailPortal architectural concepts

Les composants du portail se divisent en deux catégories logiques : le code et le contenu.The portal components can be logically divided into two categories: code and content.

Le code, conservé dans le référentiel GitHub, comprend les éléments suivants :Code is maintained in the GitHub repository and includes:

  • les widgets, qui représentent des éléments visuels et associent du code HTML, du code JavaScript, des possibilités de stylisation, des paramètres et un mappage du contenuWidgets - which represent visual elements and combine HTML, JavaScript, styling ability, settings, and content mapping. (exemples : image, paragraphe de texte, formulaire, liste d’API, etc.) ;Examples are an image, a text paragraph, a form, a list of APIs etc.
  • les définitions de style, qui spécifient les styles possibles des widgets ;Styling definitions - which specify how widgets can be styled
  • le moteur, écrit en JavaScript, qui génère des pages web statiques à partir du contenu du portail ;Engine - which generates static webpages from portal content and is written in JavaScript
  • l’éditeur visuel, qui offre une expérience de personnalisation et de création au sein du navigateur.Visual editor - which allows for in-browser customization and authoring experience

Le contenu est divisé en deux sous-catégories : le contenu du portail et le contenu de la Gestion des API.Content is divided into two subcategories: portal content and API Management content.

Le contenu du portail, propre au portail, comprend les éléments suivants :Portal content is specific to the portal and includes:

  • les pages (exemples : page de destination, tutoriels sur les API, billets de blog) ;Pages - for example, landing page, API tutorials, blog posts
  • les contenus multimédias (exemples : images, animations et autres contenus basés sur des fichiers) ;Media - images, animations, and other file-based content
  • les dispositions : modèles qui sont confrontés avec une URL et définissent le mode d’affichage des pages ;Layouts - templates, which are matched against a URL and define how pages are displayed
  • les styles : valeurs des définitions de style (exemples : polices, couleurs, bordures) ;Styles - values for styling definitions, e.g. fonts, colors, borders
  • les paramètres : configuration (exemples : favicon, métadonnées du site web).Settings - configuration, e.g. favicon, website metadata

Le contenu du portail, à l’exception des contenus multimédias, est exprimé sous la forme de documents JSON.Portal content, except for media, is expressed as JSON documents.

Le contenu Gestion des API comprend des entités telles que les API, les Opérations, les Produits et les Abonnements.API Management content includes entities such as APIs, Operations, Products, Subscriptions.

Le portail est basé sur une fourche adaptée du framework Paperbits.The portal is based on an adapted fork of the Paperbits framework. La fonctionnalité Paperbits d’origine a été étendue de façon à fournir des widgets propres à la Gestion des API (par exemple, une liste d’API ou une liste de Produits) et un connecteur vers le service Gestion des API permettant d’enregistrer et de récupérer du contenu.The original Paperbits functionality has been extended to provide API Management-specific widgets (for example, a list of APIs, a list of Products) and a connector to API Management service for saving and retrieving content.

Forum aux questionsFrequently asked questions

Dans cette section, nous répondons aux questions courantes d’ordre général sur le nouveau portail des développeurs.In this section, we answer common questions about the new developer portal, which are of general nature. Pour toute question spécifique à la version auto-hébergée, reportez-vous à la section wiki du référentiel GitHub.For questions specific to the self-hosted version, refer to the wiki section of the GitHub repository.

Comment migrer à partir de la préversion du portail ? How can I migrate from the preview version of the portal?

En utilisant la préversion du portail des développeurs, vous avez configuré le contenu en préversion dans votre service Gestion des API.By using the preview version of the developer portal, you provisioned the preview content in your API Management service. Le contenu par défaut a été sensiblement modifié dans la version en disponibilité générale afin d’offrir une meilleure expérience utilisateur.The default content has been significantly modified in the generally available version for better user experience. Il comprend également de nouveaux widgets.It also includes new widgets.

Si vous utilisez la version managée, réinitialisez le contenu du portail en cliquant sur Réinitialiser le contenu dans la section de menu Opérations.If you're using the managed version, reset the content of the portal by clicking Reset content in the Operations menu section. Une fois confirmée, cette opération supprimera tout le contenu du portail et configurera le nouveau contenu par défaut.Confirming this operation will remove all the content of the portal and provision the new default content. Le moteur du portail a été automatiquement mis à jour dans votre service Gestion des API.The portal's engine has been automatically updated in your API Management service.

Réinitialiser le contenu du portail

Si vous utilisez la version auto-hébergée, utilisez les fichiers scripts/cleanup.bat et scripts/generate.bat du référentiel GitHub pour supprimer le contenu actuel et configurer un nouveau contenu.If you're using the self-hosted version, use the scripts/cleanup.bat and scripts/generate.bat from the GitHub repository to remove existing content and provision new content. Veillez au préalable à passer à la dernière version du code de votre portail à partir du référentiel GitHub.Make sure you upgrade your portal's code to the latest release from the GitHub repository beforehand.

Si vous ne souhaitez pas réinitialiser le contenu du portail, vous pouvez utiliser les nouveaux widgets sur toutes vos pages.If you don't want to reset the content of the portal, you may consider using newly available widgets throughout your pages. Les widgets d’origine ont été automatiquement mis à jour vers les dernières versions.Existing widgets have been automatically updated to the latest versions.

Si votre portail a été configuré après l’annonce de la mise à la disposition générale, il dispose normalement déjà du nouveau contenu par défaut.If your portal was provisioned after the general availability announcement, it should already feature the new default content. Aucune action de votre part n’est nécessaire.No action is required from your side.

Comment migrer de l’ancien portail des développeurs au nouveau ?How can I migrate from the old developer portal to the new developer portal?

Les portails étant incompatibles, vous devez migrer le contenu manuellement.Portals are incompatible and you need to migrate the content manually.

Le nouveau portail a-t-il toutes les fonctionnalités de l’ancien portail ?Does the new portal have all the features of the old portal?

Le nouveau portail des développeurs ne prend pas en charge les Applications et les Problèmes.The new developer portal doesn't support Applications and Issues. Si vous avez utilisé les Problèmes sur l’ancien portail et que vous en avez besoin sur le nouveau, publiez un commentaire sur un problème GitHub dédié.If you have used Issues in the old portal and need them in the new one, post a comment in a dedicated GitHub issue.

L’authentification avec OAuth dans la console du développeur interactive n’est prise en charge.Authentication with OAuth in the interactive developer console is not yet supported. Vous pouvez suivre la progression via le problème GitHub.You can track the progress through the GitHub issue.

L’ancien portail est-il déconseillé ?Has the old portal been deprecated?

L’ancien portail des développeurs et l’ancien portail des éditeurs sont désormais des fonctionnalités héritées, qui ne recevront que des mises à jour de sécurité.The old developer and publisher portals are now legacy features - they will be receiving security updates only. Les nouvelles fonctionnalités ne seront implémentées que dans le nouveau portail des développeurs.New features will be implemented in the new developer portal only.

La dépréciation des portails hérités sera annoncée séparément.Deprecation of the legacy portals will be announced separately. Si vous avez des questions, des doutes ou des commentaires, signalez-les dans un problème GitHub dédié.If you have questions, concerns, or comments, raise them in a dedicated GitHub issue.

Les fonctionnalités dont j’ai besoin ne sont pas prises en charge dans le portailFunctionality I need isn't supported in the portal

Utilisez la version auto-hébergée et implémentez votre propre widget.Use the self-hosted version and implement your own widget.

Comment automatiser les déploiements de portails ?How can I automate portal deployments?

Vous pouvez accéder programmatiquement au contenu du portail des développeurs et le gérer avec l’API REST, que vous utilisiez une version managée ou auto-hébergée.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.

L’API est documentée dans la section wiki du référentiel GitHub.The API is documented in the GitHub repository's wiki section. Elle peut également servir à automatiser des migrations du contenu du portail entre différents environnements, par exemple d’un environnement de test vers l’environnement de production.It can also be used for automating migrations of portal content between environments - for example from a test environment to the production environment. Pour plus d’informations sur ce processus, lisez cet article de documentation sur GitHub.You can learn more about this process in this documentation article on GitHub.

Le portail prend-il en charge les modèles Azure Resource Manager ? Est-il compatible avec le kit de ressources DevOps Gestion des API ?Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?

Non.No.

Faut-il activer une connectivité de réseau virtuel supplémentaire pour les nouvelles dépendances du portail managé ?Do I need to enable additional VNet connectivity for the new managed portal dependencies?

Dans la plupart des cas, non.In most cases - no.

Si votre service de gestion des API se trouve dans un réseau virtuel interne, votre portail des développeurs est accessible uniquement à partir de ce réseau.If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. Le nom d’hôte du point de terminaison de gestion doit être résolu en adresse IP virtuelle interne du service à partir de l’ordinateur utilisé pour accéder à l’interface d’administration du portail.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. Veillez à ce que le point de terminaison de gestion soit inscrit dans le DNS.Make sure the management endpoint is registered in the DNS. En cas d’erreur de configuration, l’erreur suivante apparaît : 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 (...).

J’ai attribué un domaine de gestion des API personnalisé et le portail publié ne fonctionne pasI have assigned a custom API Management domain and the published portal doesn't work

Après avoir mis à jour le domaine, vous devez republier le portail pour que les modifications prennent effet.After you update the domain, you need to republish the portal for the changes to take effect.

J’ai ajouté un fournisseur d’identité mais il n’apparaît pas dans le portailI have added an identity provider and I can't see it in the portal

Après avoir configuré un fournisseur d’identité (par exemple, AAD, AAD B2C), vous devez republier le portail pour que les modifications prennent effet.After you configure an identity provider (for example, AAD, AAD B2C), you need to republish the portal for the changes to take effect.

J’ai configuré la délégation mais le portail ne l’utilise pasI have set up delegation and the portal doesn't use it

Après avoir configuré la délégation, vous devez republier le portail pour que les modifications prennent effet.After you set up delegation, you need to republish the portal for the changes to take effect.

Les autres modifications apportées à la configuration de la gestion des API n’ont pas été propagées dans le portail des développeursMy other API Management configuration changes haven't been propagated in the developer portal

La plupart des modifications de configuration (par exemple, réseau virtuel, connexion et conditions de produit) nécessitent une republication du portal.Most configuration changes (for example, VNet, sign-in and product terms) require republishing the portal.

J’obtiens une erreur CORS lorsque j’utilise la console interactiveI'm getting a CORS error when using the interactive console

La console interactive effectue une requête d’API côté client à partir du navigateur.The interactive console makes a client-side API request from the browser. Vous pouvez résoudre le problème CORS en ajoutant une stratégie CORS sur vos API.You can resolve the CORS problem by adding a CORS policy on your API(s). Vous pouvez spécifier tous les paramètres manuellement ou utiliser la valeur de caractère générique *.You can specify all the parameters manually or use wildcard * values. Par exemple :For example:

<cors>
    <allowed-origins>
        <origin>*</origin>
    </allowed-origins>
    <allowed-methods>
        <method>GET</method>
        <method>POST</method>
        <method>PUT</method>
        <method>DELETE</method>
        <method>HEAD</method>
        <method>OPTIONS</method>
        <method>PATCH</method>
        <method>TRACE</method>
    </allowed-methods>
    <allowed-headers>
        <header>*</header>
    </allowed-headers>
    <expose-headers>
        <header>*</header>
    </expose-headers>
</cors>

Notes

Si vous appliquez la stratégie CORS dans l’étendue du produit, au lieu de l’étendue de l’API, et que votre API utilise l’authentification par clé d’abonnement via un en-tête, votre console ne fonctionnera pas.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.

Le navigateur émet automatiquement une requête HTTP OPTIONS, qui ne contient pas d’en-tête avec la clé d’abonnement.The browser automatically issues an OPTIONS HTTP request, which doesn’t contain a header with the subscription key. La clé d’abonnement étant absente, la gestion des API ne peut pas associer l’appel OPTIONS à un produit et, par conséquent, ne peut pas appliquer la stratégie CORS.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.

Pour contourner le problème, vous pouvez transmettre la clé d’abonnement dans un paramètre de requête.As a workaround you can pass the subscription key in a query parameter.

Quelles sont les autorisations requises pour modifier le portail des développeurs ?What permissions do I need to edit the developer portal?

Si l’erreur Oops. Something went wrong. Please try again later. apparaît lorsque vous ouvrez le portail en mode d’administration, vous ne disposez peut-être pas des autorisations requises (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 (RBAC).

Les portails hérités exigeaient l’autorisation Microsoft.ApiManagement/service/getssotoken/action sur l’étendue du service (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) pour que l’administrateur d’utilisateurs puisse y accéder.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. Le nouveau portail exige l’autorisation Microsoft.ApiManagement/service/users/token/action sur l’étendue /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.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.

Vous pouvez utiliser le script PowerShell suivant pour créer un rôle avec l’autorisation requise.You can use the following PowerShell script to create a role with the required permission. Veillez à changer le paramètre <subscription-id>.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 

Une fois le rôle créé, il peut être attribué à n’importe quel utilisateur de la section Contrôle d’accès (IAM) du portail Azure.Once the role is created, it can be granted to any user from the Access Control (IAM) section in the Azure portal. Le fait d’attribuer ce rôle à un utilisateur a pour effet d’attribuer l’autorisation sur l’étendue du service.Assigning this role to a user will assign the permission at the service scope. L’utilisateur pourra générer des jetons SAS au nom de n’importe quel utilisateur du service.The user will be able to generate SAS tokens on behalf of any user in the service. Au minimum, ce rôle doit être attribué à l’administrateur du service.At the minimum, this role needs to be assigned to the administrator of the service. La commande PowerShell suivante montre comment attribuer le rôle à un utilisateur user1 sur l’étendue la plus basse pour éviter d’octroyer des autorisations inutiles à l’utilisateur :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" 

Une fois les autorisations octroyées à un utilisateur, celui-ci doit se déconnecter et se reconnecter au portail Azure pour que les nouvelles autorisations prennent effet.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.

L’erreur Unable to start the portal. See if settings are specified correctly (...) apparaîtI'm seeing the Unable to start the portal. See if settings are specified correctly (...) error

Cette erreur s’affiche lorsqu’un appel GET à https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview échoue.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. L’appel est émis à partir du navigateur par l’interface d’administration du portail.The call is issued from the browser by the administrative interface of the portal.

Si votre service de gestion des API est un réseau virtuel, reportez-vous à la question sur la connectivité du réseau virtuel ci-dessus.If your API Management service is in a VNet - refer to the VNet connectivity question above.

L’échec de l’appel peut également être dû au fait qu’un certificat SSL attribué à un domaine personnalisé ne soit pas approuvé par le navigateur.The call failure may also be caused by an SSL certificate, which is assigned to a custom domain and is not trusted by the browser. Pour remédier à ce problème, vous pouvez supprimer le domaine personnalisé de point de terminaison de gestion. La gestion des API reviendra au point de terminaison par défaut avec un certificat approuvé.As a mitigation, you can remove the management endpoint custom domain - API Management will fall back to the default endpoint with a trusted certificate.

Étapes suivantesNext steps

Découvrez le nouveau portail des développeurs :Learn more about the new developer portal:

Parcourez d’autres ressources :Browse other resources: