Étendre le portail des développeurs avec des widgets personnalisés

S’APPLIQUE À : Développeur | De base | Standard | Premium

Le portail des développeurs de Gestion des API dispose d’un éditeur visuel et de widgets intégrés pour vous permettre de personnaliser et styliser l’apparence du portail. Toutefois, il se peut que vous deviez personnaliser davantage le portail des développeurs avec des fonctionnalités personnalisées. Par exemple, vous pouvez intégrer votre portail des développeurs avec un système de support impliquant l’ajout d’une interface personnalisée. Cet article explique comment ajouter des fonctionnalités personnalisées telles que des widgets personnalisés à votre portail des développeurs de Gestion des API.

Le tableau suivant récapitule deux options, avec des liens vers plus de détails.

Utiliser un widget de code HTML personnalisé

Le portail des développeurs managé comprend un widget de code HTML personnalisé dans lequel vous pouvez insérer du code HTML pour de petites personnalisations du portail. Par exemple, vous pouvez utiliser du code HTML personnalisé pour incorporer une vidéo ou pour ajouter un formulaire. Le portail affiche le widget personnalisé dans un cadre inséré (iframe).

1. Dans l’interface d’administration du portail des développeurs, accédez à la page ou à la section où vous souhaitez insérer le widget.

2. Sélectionnez l’icône « plus » grise (+) qui s’affiche lorsque vous placez le pointeur de la souris sur la page.

3. Dans la fenêtre Ajouter un widget, sélectionnez Code HTML personnalisé.

   

4. Sélectionnez l’icône représentant un crayon pour personnaliser le widget.

5. Entrez la Largeur et la Hauteur (en pixels) du widget.

6. Pour hériter des styles du portail des développeurs (recommandé), sélectionnez Appliquer le style du portail des développeurs.

   Notes

   Si ce paramètre n’est pas sélectionné, les éléments incorporés seront des contrôles HTML bruts, sans les styles du portail des développeurs.

   

7. Remplacez l’exemple de code HTML par votre contenu personnalisé.

8. Une fois la configuration terminée, fermez la fenêtre.

9. Enregistrez vos modifications et republiez le portail.

Créer et charger un widget personnalisé

Pour des cas d’utilisation plus avancés, vous pouvez créer et charger un widget personnalisé sur le portail des développeurs. La Gestion des API fournit une structure de code pour les développeurs afin de créer des widgets personnalisés dans React, Vue ou TypeScript. La structure inclut des outils pour vous aider à développer et déployer votre widget sur le portail des développeurs.

Prérequis

• Installer Node.js runtime localement
• Connaissance de base de la programmation et du développement web

Créer un widget

1. Dans l’interface d’administration du portail des développeurs, sélectionnez Widgets personnalisés>Créer un widget personnalisé.

2. Entrez un nom de widget, puis choisissez une technologie. Pour plus d’informations, consultez Modèles de widget plus loin dans cet article.

3. Sélectionnez Créer le widget.

4. Ouvrez un terminal, accédez à l’emplacement où vous souhaitez enregistrer le code du widget, puis exécutez la commande suivante pour télécharger la structure du code :

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

5. Accédez au dossier nouvellement créé contenant la structure du code du widget.

   cd <name-of-widget>
   

6. Ouvrez le dossier dans l’éditeur de code de votre choix, tel que VS Code.

7. Installez les dépendances et démarrez le projet :

   npm install 
   npm start
   

   Votre navigateur doit ouvrir un nouvel onglet avec votre portail des développeurs connecté à votre widget en mode développement.

   Notes

   Si l’onglet ne s’ouvre pas, procédez comme suit :

   1. Assurez-vous que le serveur de développement a démarré. Pour ce faire, vérifiez la sortie sur la console où vous avez démarré le serveur à l’étape précédente. Elle devrait afficher le port sur lequel le serveur s’exécute (par exemple, http://127.0.0.1:3001).
   2. Accédez à votre service Gestion des API dans le portail Azure, puis ouvrez votre portail des développeurs avec l’interface d’administration.
   3. Ajoutez /?MS_APIM_CW_localhost_port=3001 à l’URL. Modifiez le numéro de port si votre serveur s’exécute sur un autre port.

8. Implémentez le code du widget et testez-le localement. Le code du widget se trouve dans le dossier src, dans les sous-dossiers suivants :

   • app - Code du composant de widget que les visiteurs du portail des développeurs publié voient et avec lequel ils interagissent.
   • editor - Code du composant de widget que vous utilisez dans l’interface d’administration du portail des développeurs pour modifier les paramètres du widget

   Le fichier values.ts contient les valeurs et les types par défaut des propriétés personnalisées du widget que vous pouvez activer pour modification.

   

   Les propriétés personnalisées vous permettent d’ajuster des valeurs dans l’instance du widget personnalisé à partir de l’interface utilisateur d’administration du portail des développeurs, sans modifier le code ou redéployer le widget personnalisé. Cet objet doit être passé à certaines fonctions d’assistance des widgets.

Déployer le widget personnalisé sur le portail des développeurs

1. Spécifiez les valeurs suivantes dans le fichier deploy.js situé à la racine de votre projet :

   • resourceId - ID de ressource de votre service Gestion des API, au format suivant : subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

   • managementApiEndpoint - Point de terminaison de l’API de gestion Azure (dépend de votre environnement, généralement management.azure.com).

   • apiVersion - Facultatif, utiliser pour remplacer la version de l’API de gestion par défaut.

2. Exécutez la commande suivante :

   npm run deploy
   

   Si vous y êtes invité, connectez-vous à votre compte Azure.

   Remarque

   Quand vous êtes invité à vous connecter, vous devez utiliser un compte membre du locataire Microsoft Entra ID associé à l’abonnement Azure où réside votre service Gestion des API. Le compte ne doit pas être un invité ou un compte fédéré, et doit avoir l’autorisation appropriée pour accéder à l’interface administrative du portail.

Le widget personnalisé est maintenant déployé sur votre portail des développeurs. À l’aide de l’interface d’administration du portail, vous pouvez l’ajouter à des pages du portail des développeurs, et définir des valeurs pour toute propriété personnalisée configurée dans le widget.

Publier le portail des développeurs

Après avoir configuré le widget dans l’interface d’administration, republiez le portail afin de rendre le widget disponible en production.

Modèles de widget

Nous fournissons des modèles pour les technologies suivantes, que vous pouvez utiliser pour le widget :

• TypeScript (implémentation pure sans infrastructure)
• React
• Vue

Tous les modèles sont basés sur le langage de programmation TypeScript.

Le modèle React contient des hooks personnalisés préparés dans le fichier hooks.ts, et des fournisseurs établis pour le partage du contexte via l’arborescence des composants avec des hooks dédiés useSecrets, useValues et useEditorValues.

Utiliser le package @azure/api-management-custom-widgets-tools

Ce package npm contient les fonctions suivantes pour vous aider à développer votre widget personnalisé, et fournit des fonctionnalités, dont la communication entre le portail des développeurs et votre widget :

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

Fonction qui retourne un objet JSON contenant les valeurs que vous avez définies dans l’éditeur de widget, combinées avec des valeurs par défaut, passées en tant qu’argument.

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

Elle est destinée à être utilisée dans la partie runtime (app) de votre widget.

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

Fonction qui opère de la même façon que getValues, mais retourne uniquement les valeurs que vous avez définies dans l’éditeur.

Elle est destinée à être utilisée dans l’éditeur de votre widget, mais fonctionne également dans un runtime.

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

Accepte un type TypeScript et retourne une fonction pour mettre à jour les valeurs du widget. La fonction retournée prend en tant que paramètre un objet JSON avec des valeurs mises à jour, et ne retourne rien.

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

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

Cette fonction retourne une promesse JavaScript qui, après résolution, retourne un objet JSON de données nécessaire pour communiquer avec le serveur principal. token est nécessaire pour l’authentification. userId est nécessaire pour interroger des ressources spécifiques de l’utilisateur. Il se peut que ces valeurs ne soient pas définies lors de l’affichage du portail par un utilisateur anonyme. L’objet Secrets contient également managementApiUrl, l’URL du serveur principal de votre portail, et apiVersion, l’apiVersion actuellement utilisée par le portail des développeurs.

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

Cette fonction déploie votre widget sur votre stockage d’objets blob. Dans tous les modèles, elle est préconfigurée dans le fichier deploy.js.

Elle accepte trois arguments par défaut :

• serviceInformation - Informations sur votre service Azure :

  • resourceId - ID de ressource de votre service Gestion des API, au format suivant : subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

  • managementApiEndpoint - Point de terminaison de l’API de gestion Azure (dépend de votre environnement, généralement management.azure.com).

• ID de votre widget : nom de votre widget au format « convivial PC » (caractères minuscules alphanumériques latins et tirets ; Contoso widget devient contoso-widget). Vous pouvez le trouver dans le package.json sous la clé name.

• fallbackConfigPath - Chemin d’accès du fichier local config.msapim.json , par exemple, ./static/config.msapim.json.

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

Cette fonction retourne toutes les données transmises à votre widget personnalisé à partir du portail des développeurs. Elle contient d’autres données qui peuvent être utiles à des fins le débogage ou dans des scénarios plus avancés. Cette API est censée changer en lien avec des changements cassants potentiels. Elle retourne un objet JSON contenant les clés suivantes :

• values - Toutes les valeurs que vous avez définies dans l’éditeur, le même objet que celui retourné par getEditorData.

• instanceId - ID de cette instance du widget.

Ajouter ou supprimer des propriétés personnalisées

Les propriétés personnalisées vous permettent d’ajuster des valeurs dans le code du widget personnalisé à partir de l’interface utilisateur d’administration du portail des développeurs, sans modifier le code ou redéployer le widget personnalisé. Par défaut, les champs d’entrée pour quatre propriétés personnalisées sont définis. Vous pouvez ajouter ou supprimer d’autres propriétés personnalisées si nécessaire.

Pour ajouter une propriété personnalisée :

1. Dans le fichier src/values.ts, ajoutez au type Values le nom de la propriété et le type des données qu’elle enregistrera.
2. Dans le même fichier, ajoutez une valeur par défaut pour celle-ci.
3. Accédez au fichier editor.html ou editor/index (l’emplacement exact dépend de l’infrastructure que vous avez choisie), puis dupliquez une entrée existante ou ajoutez-en une vous-même.
4. Vérifiez que le champs d’entrée signale la valeur modifiée de la fonction onChange, que vous pouvez obtenir à partir de buildOnChange.

(Facultatif) Utiliser une autre infrastructure

Pour implémenter votre widget à l’aide d’une autre infrastructure et d’autres bibliothèques d’interface utilisateur JavaScript, vous devez configurer le projet vous-même en suivant les instructions suivantes :

• Dans la plupart des cas, nous vous recommandons de commencer à partir du modèle TypeScript.
• Installez les dépendances comme dans tout autre projet npm.
• Si l’infrastructure choisie n’est pas compatible avec l’outil de build Vite, configurez-la pour qu’elle sorte les fichiers compilés dans le dossier ./dist. Si vous le souhaitez, redéfinissez l’emplacement des fichiers compilés en fournissant un chemin relatif en guise de quatrième argument de la fonction deployNodeJs.
• Pour le développement local, le fichier config.msapim.json doit être accessible à l’URL localhost:<port>/config.msapim.json lorsque le serveur est en cours d’exécution.

Créer des widgets personnalisés à l’aide de React Component Toolkit

Le React Component Toolkit open source fournit une suite de scripts de package npm pour vous aider à convertir une application React en infrastructure de widget personnalisée, à la tester et à déployer le widget personnalisé dans le portail des développeurs. Si vous avez accès à un service Azure OpenAI, le kit de ressources peut également créer un widget à partir d’une description de texte que vous fournissez.

Pour le moment, vous pouvez utiliser le kit de ressources de deux façons pour déployer un widget personnalisé :

• Manuellement, en installant le kit de ressources et en exécutant les scripts de package npm localement. Vous exécutez les scripts de manière séquentielle pour créer, tester et déployer un composant React en tant que widget personnalisé sur le portail des développeurs.
• À l’aide d’un modèle Azure Developer CLI (azd) pour un déploiement de bout en bout. Le modèle azd déploie une instance Gestion des API Azure et une instance Azure OpenAI. Une fois les ressources fournies, un script interactif vous aide à créer, tester et déployer un widget personnalisé sur le portail des développeurs à partir d’une description que vous fournissez.

Contenu connexe

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

• Vue d’ensemble du portail des développeurs Gestion des API Azure
• Forum aux questions
• Structure d’un widget personnalisé pour le portail des développeurs du service Gestion des API Azure
• Outils pour travailler avec les widgets personnalisés du portail des développeurs du service Gestion des API Azure