Tutoriel : Accéder et personnaliser le portail des développeurs

Le portail des développeurs est un site web généré automatiquement et entièrement personnalisable avec la documentation de vos API. C’est là que les consommateurs d’API peuvent découvrir vos API, apprendre à les utiliser et y demander l’accès.

Dans ce tutoriel, vous allez apprendre à :

• Accéder à la version managée du portail des développeurs
• Parcourir son interface d’administration
• Personnaliser le contenu
• Publier les modifications
• Afficher le portail publié

Pour plus d’informations sur le portail des développeurs, voir la Vue d’ensemble du portail des développeurs Gestion des API Azure.

Prérequis

• Suivez ce guide de démarrage rapide : Créer une instance du service Gestion des API Azure
• Importer et publier une API. Pour plus d’informations, voir Importer et publier.

Disponibilité

Important

Cette fonctionnalité est disponible dans les niveaux Premium, Standard, De base et Développeur de Gestion des API.

Accéder au portail en tant qu’administrateur

Suivez les étapes ci-dessous pour accéder à la version managée du portail.

1. Dans le portail Azure, accédez à votre instance APIM.
2. Sélectionnez le bouton Portail des développeurs dans la barre de navigation supérieure. Un nouvel onglet de navigateur s’ouvre, en affichant une version d’administration du portail.

Concepts architecturaux du portail des développeurs

Les composants du portail se divisent en deux catégories logiques : le code et le contenu.

Code

Le code, qui est conservé dans le dépôt GitHub du portail des développeurs Gestion des API comprend les éléments suivants :

• Widgets : représentent des éléments visuels et associent du code HTML, du code JavaScript, des possibilités d’application de styles, des paramètres et un mappage du contenu. (exemples : image, paragraphe de texte, formulaire, liste d’API, etc.) ;
• Définitions de styles : spécifient comment des styles peuvent être appliqués aux widgets
• Moteur : génère des pages web statiques à partir du contenu du portail, écrit en JavaScript
• Éditeur visuel : offre une expérience de personnalisation et de création dans le navigateur

Contenu

Le contenu est divisé en deux sous-catégories : le contenu du portail et le contenu de la Gestion des API.

Le contenu du portail, propre au portail, comprend les éléments suivants :

• Pages : par exemples, la page de destination, les tutoriels sur les API, les billets de blog

• Contenus multimédias : images, animations et autres contenus basés sur des fichiers

• Dispositions : modèles qui sont mis en correspondance avec une URL et qui définissent le mode d’affichage des pages

• Styles : valeurs des définitions de styles, comme les polices, les couleurs, les bordures

• Paramètres : configurations comme favicon, les métadonnées de site web

  Le contenu du portail, à l’exception des contenus multimédias, est exprimé sous la forme de documents JSON.

Le contenu Gestion des API comprend des entités telles que les API, les Opérations, les Produits et les Abonnements.

Comprendre l’interface d’administration du portail

Contenu par défaut

Si vous accédez au portail pour la première fois, le contenu par défaut est automatiquement provisionné en arrière-plan. Il a été conçu pour présenter les fonctionnalités du portail et réduire les personnalisations nécessaires à la particularisation de votre portail. Pour plus d’informations sur le contenu du portail, voir la Vue d’ensemble du portail des développeurs Gestion des API Azure.

Éditeur visuel

Il est possible de personnaliser le contenu du portail avec l’éditeur visuel.

• Les sections de menu de gauche permettent de créer ou de modifier des pages, des médias, des dispositions, des menus, des styles ou des paramètres de site web.
• Les éléments de menu situés en bas de l’écran vous permettent de passer d’une fenêtre à l’autre (par exemple, mobile ou bureau), de visualiser les éléments du portail visibles par les utilisateurs de différents groupes, ou encore d’enregistrer ou d’annuler des actions.
• Ajoutez des sections à une page en cliquant sur une icône bleue dotée d’un signe plus.
• Pour ajouter des widgets (par exemple, du texte, des images ou une liste d’API), appuyez sur une icône grise accompagnée d’un signe plus.
• Réorganisez les éléments d’une page avec l’interaction de type glisser-déplacer.

Dispositions et pages

Les dispositions définissent la façon dont s’affichent les pages. Par exemple, dans le contenu par défaut, il existe deux dispositions : l’une s’applique à la page d’accueil et l’autre à toutes les autres pages.

Pour appliquer une disposition à une page, faites correspondre son modèle d’URL à son URL. Par exemple, une disposition associée au modèle d’URL /wiki/* s’appliquera à chacune des pages dont l’URL comporte le segment /wiki/ : /wiki/getting-started, /wiki/styles, etc.

Dans l’image précédente, le contenu appartenant à la disposition est marqué en bleu, tandis que la page est marquée en rouge. Les sections de menu sont marquées de la même manière.

Guide de style

Le guide de style est un panneau destiné aux concepteurs. Il permet de contrôler et de styliser tous les éléments visuels du portail. Le style est hiérarchique : de nombreux éléments héritent des propriétés d’autres éléments. Par exemple, les éléments de type bouton utilisent des couleurs du texte et de l’arrière-plan. Pour modifier la couleur d’un bouton, il faut modifier la variante de couleur d’origine.

Pour modifier une variante, sélectionnez-la, puis sélectionnez l’icône de crayon qui apparaît au-dessus. Après avoir effectué les modifications dans la fenêtre contextuelle, fermez-la.

Bouton Enregistrer

Chaque fois que vous apportez une modification au portail, vous devez l’enregistrer manuellement en sélectionnant le bouton Enregistrer dans le menu du bas, ou en appuyant sur [Ctrl]+[S]. Le contenu modifié est alors automatiquement chargé dans votre service Gestion des API.

Personnaliser le contenu du portail

Avant de mettre le portail à la disposition des visiteurs, il est préférable de personnaliser le contenu généré automatiquement. Sont recommandées les modifications suivantes : dispositions, styles et contenu de la page d’accueil. Vous pouvez également rendre certains éléments de contenu accessibles uniquement aux utilisateurs ou groupes sélectionnés.

Notes

Pour des raisons d’intégration, les pages suivantes ne sont ni supprimables ni déplaçables sous une autre URL : /404, /500, /captcha, /change-password, /config.json, /confirm/invitation, /confirm-v2/identities/basic/signup, /confirm-v2/password, /internal-status-0123456789abcdef, /publish, /signin, /signin-sso et /signup.

page d'accueil

La page d’Accueil par défaut comporte du contenu d’espace réservé. Vous pouvez soit supprimer des sections entières comportant ce contenu, soit conserver la structure et ajuster les éléments un par un. Remplacez le texte et les images générés par les vôtres en veillant à ce que les liens pointent vers les emplacements souhaités. Vous pouvez modifier la structure et le contenu de la page d’accueil de la façon suivante :

• Glisser-déplacer des éléments de page vers l’emplacement souhaité sur le site.
• Sélection des éléments de texte et d’en-tête pour modifier et mettre en forme le contenu.
• La vérification de vos boutons pointe vers les emplacements appropriés.

Mises en forme

Remplacez le logo généré automatiquement dans la barre de navigation par votre propre image.

1. Dans le portail des développeurs, sélectionnez le logo par défaut Contoso en haut à gauche de la barre de navigation.
2. Sélectionnez l’icône Éditer.
3. Sous la section Principal, sélectionnez Source.
4. Dans la fenêtre contextuelle Média, sélectionnez soit :
   • une image déjà téléchargée dans votre bibliothèque, soit
   • Charger un fichier pour charger un nouveau fichier d’image à utiliser, soit
   • Sélectionnez Aucun pour renoncer à utiliser un logo.
5. Le logo est mis à jour en temps réel.
6. Cliquez en dehors des fenêtres contextuelles pour quitter la bibliothèque multimédia.
7. Cliquez sur Save.

Style

Même si vous n’avez pas besoin de modifier les styles, vous pouvez éventuellement ajuster des éléments spécifiques. Par exemple, choisissez la couleur principale en fonction de la couleur de votre marque. Il existe deux méthodes pour le faire :

Style de site général

1. Dans le portail des développeurs, sélectionnez l’icône Styles dans la barre d’outils de gauche.
2. Sous la section Couleurs, sélectionnez l’élément du style de couleur que vous voulez modifier.
3. Cliquez sur l’icône Modifier pour cet élément de style.
4. Sélectionnez la couleur dans le sélecteur de couleurs ou entrez le code de couleur hexadécimal.
5. Ajoutez et nommez un autre élément de couleur en cliquant sur Ajouter une couleur.
6. Cliquez sur Save.

Style de conteneur

1. Sur la page principale du portail des développeurs, sélectionnez l’arrière-plan du conteneur.
2. Sélectionnez l’icône Modifier.
3. Dans la fenêtre contextuelle, définissez :
   • l’arrière-plan à effacer, une image, une couleur spécifique ou à un dégradé
   • la taille du conteneur, la marge et marge intérieure.
   • la position et la hauteur du conteneur.
4. Cliquez en dehors des fenêtres contextuelles pour quitter les paramètres du conteneur.
5. Cliquez sur Save.

Contrôles de visibilité et d’accès

Vous pouvez contrôler le contenu du portail qui apparaît à différents utilisateurs, en fonction de leur identité. Par exemple, vous souhaiterez peut-être afficher certaines pages uniquement pour les utilisateurs qui ont accès à un produit ou à une API spécifique. Vous pouvez également faire apparaître une section d’une page uniquement pour certains groupes d’utilisateurs. Le portail des développeurs dispose de contrôles intégrés pour ces besoins.

Notes

Les contrôles de visibilité et d’accès sont pris en charge uniquement dans le portail des développeurs managés. Ils ne sont pas pris en charge dans le portail auto-hébergé.

• Lorsque vous ajoutez ou modifiez une page, sélectionnez l’onglet Accès pour contrôler les utilisateurs ou les groupes qui peuvent accéder à la page

  

• Lorsque vous personnalisez le contenu d’une page, tel qu’une section de page, un menu ou un bouton, sélectionnez l’icône Modifier la visibilité pour contrôler les utilisateurs ou les groupes qui peuvent voir l’élément sur la page

  

  • Vous pouvez modifier la visibilité du contenu de la page suivante : sections, menus, boutons et connexion pour l’autorisation OAuth.

  • Les fichiers multimédias tels que les images d’une page héritent de la visibilité des éléments qui les contiennent.

Lorsqu’un utilisateur visite le portail des développeurs avec des contrôles de visibilité et d’accès appliqués :

• Le portail des développeurs masque automatiquement les boutons ou les éléments de navigation qui pointent vers des pages auxquelles un utilisateur n’a pas accès.

• Une tentative par un utilisateur d’accéder à une page pour laquelle il n’est pas autorisé entraîne une erreur 404 Introuvable.

Conseil

À l’aide de l’interface d’administration, vous pouvez afficher un aperçu des pages en tant qu’utilisateur associé à n’importe quel groupe intégré ou personnalisé en sélectionnant l’icône Emprunter l’identité dans le menu en bas.

Exemple de personnalisation

Dans la vidéo suivante, nous expliquons comment modifier le contenu du portail, personnaliser l’aspect du site web et publier les modifications.

Publier le portail

Pour que votre portail et ses dernières modifications soient accessibles aux visiteurs, vous devez le publier. Vous pouvez publier le portail dans l’interface d’administration du portail ou à partir du portail Azure.

Publier à partir de l’interface d’administration

1. Veillez à enregistrer vos modifications en sélectionnant l’icône Enregistrer.

2. Dans la section Opérations du menu, sélectionnez Publier le site web. Cette opération peut prendre quelques minutes.

   

Publier à partir du portail Azure

1. Dans le portail Azure, accédez à votre instance APIM.

2. Dans le menu de gauche, sous Portail des développeurs, sélectionnez Vue d’ensemble du portail.

3. Dans la fenêtre Vue d’ensemble du portail, sélectionnez Publier.

   

Notes

Le portail doit être publié de nouveau après des modifications de configuration du service Gestion des API. Par exemple, vous publiez de nouveau le portail après l’attribution d’un domaine personnalisé, la mise à jour des fournisseurs d’identité, la définition de la délégation ou la spécification de la connexion et des conditions d’utilisation du produit.

Consulter le portail publié

Une fois publié, le portail est accessible à la même URL que le panneau d’administration, par exemple https://contoso-api.developer.azure-api.net. Affichez-le dans une session de navigateur distincte (par le biais du mode de navigation incognito ou privée) en tant que visiteur externe.

Appliquer la stratégie CORS sur les API

Pour permettre aux visiteurs de votre portail de tester les API via la console interactive intégrée, activez CORS (cross-origin resource sharing) sur vos API. Pour plus d’informations, consultez les Questions fréquentes du portail des développeurs Gestion des API Azure.

Étapes suivantes

Pour plus d’informations sur le portail des développeurs :

• Vue d’ensemble du portail des développeurs Gestion des API Azure
• Migrer vers le nouveau portail des développeurs à partir du portail hérité déprécié.
• Configurez l’authentification auprès du portail des développeurs avec des noms d’utilisateur et des mots de passe, Azure AD ou Azure AD B2C.
• Apprenez-en davantage la personnalisation et l’extension de la fonctionnalité du portail des développeurs.