Auto-héberger le portail développeurs de gestion des API

2025-05-21

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

Ce tutoriel explique comment héberger automatiquement le portail des développeurs Gestion des API. L’hébergement automatique est l’une des options permettant d’étendre les fonctionnalités du portail des développeurs. Par exemple, vous pouvez héberger automatiquement plusieurs portails pour votre instance Gestion des API, avec différentes fonctionnalités. Lorsque vous hébergez automatiquement un portail, vous devenez son responsable de la maintenance et vous êtes responsable de ses mises à niveau.

Important

Envisagez d’héberger automatiquement le portail des développeurs uniquement lorsque vous devez modifier le cœur de la base de code du portail des développeurs. Cette option nécessite une configuration avancée, notamment :

Déploiement sur une plateforme d’hébergement, éventuellement fronté par une solution telle que CDN pour une disponibilité et des performances accrues
Maintenance et gestion de l’infrastructure d’hébergement
Mises à jour manuelles, notamment pour les correctifs de sécurité, qui peuvent vous obliger à résoudre les conflits de code lors de la mise à niveau du codebase

Remarque

Le portail auto-hébergé ne prend pas en charge la visibilité et les contrôles d’accès disponibles dans le portail des développeurs gérés.

Si vous avez déjà chargé ou modifié des fichiers multimédias dans le portail géré, consultez Passer d’une version gérée à l’auto-hébergé, plus loin dans cet article.

Conditions préalables

Pour configurer un environnement de développement local, vous devez disposer des éléments suivants :

Une instance du service Gestion des API. Si vous n’en avez pas, consultez Démarrage rapide : Créer une instance Gestion des API Azure.
Un compte de stockage Azure avec la fonctionnalité sites web statiques activée. Consultez Créer un compte de stockage.
Installez Git sur votre ordinateur. Installez-le en suivant ce tutoriel Git.
Node.js (version LTS ou v10.15.0 ultérieure) et npm sur votre ordinateur. Consultez Téléchargement et installation de Node.js et npm.
Azure CLI. Suivez les étapes d’installation d’Azure CLI.

Étape 1 : Configurer l’environnement local

Pour configurer votre environnement local, vous devez cloner le référentiel, basculer vers la dernière version du portail des développeurs et installer des packages npm.

Clonez le dépôt api-management-developer-portal à partir de GitHub :

git clone https://github.com/Azure/api-management-developer-portal.git

Accédez à votre copie locale du dépôt :
```
cd api-management-developer-portal
```
Consultez la dernière version du portail.

Avant d’exécuter le code suivant, vérifiez la balise de mise en production actuelle dans la section Versions du référentiel et remplacez <current-release-tag> la valeur par la dernière balise de mise en production.
```
git checkout <current-release-tag>
```
Installez les packages npm disponibles :
```
npm install
```

Conseil / Astuce

Utilisez toujours la dernière version du portail et gardez votre portail forké up-toà jour. Les ingénieurs logiciels utilisent la master branche de ce référentiel à des fins de développement quotidiennes. Il comporte des versions instables du logiciel.

Étape 2 : Configurer des fichiers JSON, un site web statique et des paramètres CORS

Le portail des développeurs nécessite que l’API REST Gestion des API gère le contenu.

fichier config.design.json

Accédez au src dossier et ouvrez le config.design.json fichier.

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

Configurez le fichier :

Dans la managementApiUrl valeur, remplacez <service-name> par le nom de votre instance Gestion des API. Si vous avez configuré un domaine personnalisé, utilisez-le à la place (par exemple). https://management.contoso.com
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...
```
Créez manuellement un jeton SAP pour activer l’accès direct de l’API REST à votre instance Gestion des API.
Copiez le jeton généré et collez-le managementApiAccessToken comme valeur.
Dans la backendUrl valeur, remplacez <service-name> par le nom de votre instance Gestion des API. Si vous avez configuré un domaine personnalisé, utilisez-le à la place (par exemple). https://portal.contoso.com
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```
Si vous souhaitez activer CAPTCHA dans votre portail des développeurs, définissez "useHipCaptcha": true. Veillez à configurer les paramètres CORS pour le serveur principal du portail des développeurs.
Dans integration, sous googleFonts, si vous le souhaitez, définissez apiKey sur une clé API Google qui autorise l’accès à l’API développeur de polices web. Cette clé est nécessaire uniquement si vous souhaitez ajouter des polices Google dans la section Styles de l’éditeur du portail des développeurs.

Si vous n’avez pas encore de clé, vous pouvez en configurer une à l’aide de la console Google Cloud. Suivez ces étapes :
1. Ouvrez la console Google Cloud.
2. Vérifiez si l’API développeur de polices web est activée. Si ce n’est pas le cas, activez-le.
3. Sélectionnez Créer des informations d’identification>clé API.
4. Dans la boîte de dialogue ouverte, copiez la clé générée et collez-la comme valeur de apiKey dans le fichier config.design.json.
5. Sélectionnez Modifier la clé API pour ouvrir l’éditeur de clés.
6. Dans l’éditeur, sous restrictions d’API, sélectionnez Restreindre la clé. Dans la liste déroulante, sélectionnez l’API développeur de polices web.
7. Cliquez sur Enregistrer.

fichier config.publish.json

Accédez au src dossier et ouvrez le config.publish.json fichier.

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Configurez le fichier :

Copiez et collez les valeurs managementApiUrl et managementApiAccessToken du fichier de configuration précédent.
Si vous souhaitez activer CAPTCHA dans votre portail des développeurs, définissez "useHipCaptcha": true. Veillez à configurer les paramètres CORS pour le serveur principal du portail des développeurs.

fichier config.runtime.json

Accédez au src dossier et ouvrez le config.runtime.json fichier.

{
  "environment": "runtime",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "backendUrl": "https://<service-name>.developer.azure-api.net"
}

Configurez le fichier :

Copiez et collez la managementApiUrl valeur du fichier de configuration précédent.
Dans la backendUrl valeur, remplacez <service-name> par le nom de votre instance Gestion des API. Si vous avez configuré un domaine personnalisé, utilisez-le à la place (par exemple). https://portal.contoso.com
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```

Configurer le site web statique

Configurez la fonctionnalité de site web statique dans votre compte de stockage en fournissant des itinéraires vers les pages d’index et d’erreur :

Accédez à votre compte de stockage dans le portail Azure et sélectionnez Site web statique dans le menu de gauche.
Dans la page du site web statique , sélectionnez Activé.
Dans le champ Nom du document Index , entrez index.html.
Dans le champ Chemin d’accès du document d’erreur , entrez 404/index.html.
Cliquez sur Enregistrer.

Configurer les paramètres CORS pour le compte de stockage

Configurez les paramètres CORS (Cross-Origin Resource Sharing) pour le compte de stockage :

Accédez à votre compte de stockage dans le portail Azure et sélectionnez CORS dans le menu de gauche.
Sous l’onglet Service Blob , configurez les règles suivantes :

Règle Valeur

Origines autorisées *

Méthodes autorisées Sélectionnez tous les verbes HTTP.

En-têtes autorisés *

En-têtes exposés *

Âge maximal 0
Cliquez sur Enregistrer.

Règle	Valeur
Origines autorisées	*
Méthodes autorisées	Sélectionnez tous les verbes HTTP.
En-têtes autorisés	*
En-têtes exposés	*
Âge maximal	0

Configurer les paramètres CORS pour le serveur principal du portail des développeurs

Configurez les paramètres CORS pour le back-end du portail des développeurs afin d’autoriser les demandes provenant de votre portail de développeur auto-hébergé. Le portail des développeurs auto-hébergé s’appuie sur le point de terminaison principal du portail des développeurs (défini dans backendUrl les fichiers de configuration du portail) pour activer plusieurs fonctionnalités, notamment :

Vérification CAPTCHA
Autorisation OAuth 2.0 dans la console de test
Délégation de l’authentification utilisateur et de l’abonnement produit

Pour ajouter des paramètres CORS :

Accédez à votre instance Gestion des API dans le portail Azure, puis sélectionnezles paramètres du > des développeurs dans le menu de gauche.
Sous l’onglet Configuration du portail auto-hébergé , ajoutez une ou plusieurs valeurs de domaine Origin . Par exemple:
- Domaine dans lequel le portail auto-hébergé est hébergé, par exemple https://www.contoso.com
- localhost pour le développement local (le cas échéant), comme http://localhost:8080 ou https://localhost:8080
Cliquez sur Enregistrer.

Étape 3 : Exécuter le portail

Vous pouvez maintenant générer et exécuter une instance de portail local en mode de développement. En mode développement, toutes les optimisations sont désactivées et les cartes sources sont activées.

Exécutez la commande suivante:

npm start

Après une courte période, le navigateur par défaut s’ouvre automatiquement avec votre instance du portail des développeurs local. L’adresse par défaut est http://localhost:8080, mais le port peut changer s’il 8080 est déjà occupé. Toute modification apportée à la base de code du projet déclenche une reconstruction et actualise votre fenêtre de navigateur.

Étape 4 : Modifier via l’éditeur visuel

Utilisez l’éditeur visuel pour effectuer ces tâches :

Personnaliser votre portail
Contenu de l’auteur
Organiser la structure du site web
Styliser son apparence

Consultez le tutoriel : Accéder au portail des développeurs et personnaliser celui-ci. Il couvre les principes de base de l’interface utilisateur administrative et répertorie les modifications recommandées apportées au contenu par défaut. Enregistrez toutes les modifications dans l’environnement local, puis appuyez sur Ctrl+C pour la fermer.

Étape 5 : Publier localement

Au départ, les données du portail se présentent sous la forme d’objets fortement typés. La commande suivante les traduit en fichiers statiques et place la sortie dans le ./dist/website répertoire :

npm run publish

Étape 6 : Téléverser des fichiers statiques dans un blob

Utilisez Azure CLI pour charger les fichiers statiques générés localement dans un objet blob et vous assurer que vos visiteurs peuvent y accéder :

Ouvrez l’invite de commandes Windows, PowerShell ou une autre interface de commande.
Exécutez la commande Azure CLI suivante.

Remplacez <account-connection-string> par la chaîne de connexion de votre compte de stockage. Vous pouvez l’obtenir à partir de la section Clés d’accès de votre compte de stockage.
```
az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>
```

Étape 7 : Accéder à votre site web

Votre site web est désormais actif sous le nom d’hôte spécifié dans vos propriétés stockage Azure (point de terminaison principal dans les sites web statiques).

Étape 8 : Modifier les modèles de notification Gestion des API

Remplacez l’URL du portail des développeurs dans les modèles de notification Gestion des API pour pointer vers votre portail auto-hébergé. Découvrez comment configurer des notifications et des modèles d’e-mail dans Gestion des API Azure.

En particulier, effectuez les modifications suivantes apportées aux modèles par défaut :

Remarque

Les valeurs des sections mises à jour suivantes supposent que vous hébergez le portail à l’adresse https://portal.contoso.com/.

Confirmation des modifications par e-mail

Mettez à jour l’URL du portail des développeurs dans le modèle de notification de confirmation de modification par e-mail :

Contenu d’origine

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Mis à jour

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Confirmation du nouveau compte de développeur

Mettez à jour l’URL du portail des développeurs dans le modèle de notification de confirmation du nouveau compte de développeur :

Contenu d’origine

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Mis à jour

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Inviter un utilisateur

Mettez à jour l’URL du portail des développeurs dans le modèle de notification de l’utilisateur Inviter :

Contenu d’origine

<a href="$ConfirmUrl">$ConfirmUrl</a>

Mis à jour

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Nouvel abonnement activé

Mettez à jour l’URL du portail des développeurs dans le modèle de notification activé pour le nouvel abonnement :

Contenu d’origine

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Mis à jour

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Contenu d’origine

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Mis à jour

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Contenu d’origine

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Mis à jour

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Contenu d’origine

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

Mis à jour

<!--Remove the entire block of HTML code above.-->

Confirmation du changement de mot de passe

Mettez à jour l’URL du portail des développeurs dans le modèle de notification de confirmation de modification de mot de passe :

Contenu d’origine

<a href="$DevPortalUrl">$DevPortalUrl</a>

Mis à jour

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Tous les modèles

Mettez à jour l’URL du portail des développeurs dans n’importe quel modèle qui a un lien dans le pied de page :

Contenu d’origine

<a href="$DevPortalUrl">$DevPortalUrl</a>

Mis à jour

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

Passer d’un portail de développement auto-hébergé au portail des développeurs auto-hébergé

Au fil du temps, vos besoins métier peuvent changer. Vous pouvez vous retrouver dans une situation où la version gérée du portail des développeurs Gestion des API ne répond plus à vos besoins. Par exemple, une nouvelle exigence peut vous forcer à créer un widget personnalisé qui s’intègre à un fournisseur de données tiers. Contrairement à la version gérée, la version auto-hébergée du portail vous offre une flexibilité et une extensibilité complètes.

Processus de transition

Vous pouvez passer de la version managée à une version auto-hébergée au sein de la même instance de service Gestion des API. Le processus conserve les modifications que vous avez effectuées dans la version gérée du portail. Veillez à sauvegarder le contenu du portail au préalable. Vous trouverez le script de sauvegarde dans le scripts dossier du dépôt GitHub du portail des développeurs Gestion des API.

Le processus de conversion est presque identique à la configuration d’un portail auto-hébergé générique, comme indiqué dans les étapes précédentes de cet article. Il existe une exception dans l’étape de configuration. Le compte de stockage dans le config.design.json fichier doit être identique au compte de stockage de la version gérée du portail. Consultez le tutoriel : Utiliser une identité affectée par le système de machine virtuelle Linux pour accéder au stockage Azure via des informations d’identification SAP pour obtenir des instructions sur la récupération de l’URL SAP.

Conseil / Astuce

Nous vous recommandons d’utiliser un compte de stockage distinct dans le config.publish.json fichier. Cette approche vous donne plus de contrôle et simplifie la gestion du service d’hébergement de votre portail.

En savoir plus sur les autres approches pour l’auto-hébergement

Partager via

Auto-héberger le portail développeurs de gestion des API

Conditions préalables

Étape 1 : Configurer l’environnement local

Étape 2 : Configurer des fichiers JSON, un site web statique et des paramètres CORS

fichier config.design.json

fichier config.publish.json

fichier config.runtime.json

Configurer le site web statique

Configurer les paramètres CORS pour le compte de stockage

Configurer les paramètres CORS pour le serveur principal du portail des développeurs

Étape 3 : Exécuter le portail

Étape 4 : Modifier via l’éditeur visuel

Étape 5 : Publier localement

Étape 6 : Téléverser des fichiers statiques dans un blob

Étape 7 : Accéder à votre site web

Étape 8 : Modifier les modèles de notification Gestion des API

Confirmation des modifications par e-mail

Confirmation du nouveau compte de développeur

Inviter un utilisateur

Nouvel abonnement activé

Confirmation du changement de mot de passe

Tous les modèles

Passer d’un portail de développement auto-hébergé au portail des développeurs auto-hébergé

Processus de transition

Contenu connexe

Commentaires

Ressources supplémentaires