Auto-héberger le portail des développeurs Gestion des API

  • Article

S’APPLIQUE À : Développeur | Essentiel | Standard | Premium

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

Important

Envisagez d’auto-héberger le portail des développeurs uniquement lorsque vous devez modifier le cœur du codebase du portail de développement. Cette option nécessite une configuration avancée, à savoir :

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

Notes

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

Si vous avez déjà chargé ou modifié des fichiers multimédias dans le portail managé, consultez Passer du portail des développeurs managé au portail auto-hébergé, plus loin dans cet article.

Prérequis

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

Étape 1 : Configurer votre environnement local

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

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

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

  2. Accédez à la copie locale du dépôt :

    cd api-management-developer-portal

  3. Découvrez la dernière version du portail.

    Avant d’exécuter le code suivant, vérifiez l’étiquette de la version actuelle dans la section Releases du dépôt et remplacez la valeur <current-release-tag> par l’étiquette de version la plus récente.

    git checkout <current-release-tag>

  4. Installez tous les packages npm disponibles :

    npm install

Conseil

Utilisez toujours la dernière version du portail et maintenez à jour votre portail dupliqué. Les ingénieurs logiciels utilisent la branche master de ce dépôt pour leurs tâches de développement quotidiennes. Cette branche contient 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 l’API REST Gestion des API pour gérer le contenu.

Fichier config.design.json

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

{
  "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 :

  1. Dans la valeur managementApiUrl, 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"
...

  2. Créez manuellement un jeton SAS pour activer l’accès direct de l’API REST à votre instance Gestion des API.

  3. Copiez le jeton généré et collez-le en tant que valeur managementApiAccessToken.

  4. Dans la valeur backendUrl, 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"
...

  5. Si vous souhaitez activer CAPTCHA dans votre portail des développeurs, définissez "useHipCaptcha": true. Veillez à configurer les paramètres CORS pour le back-end du portail des développeurs.

  6. Dans integration, sous googleFonts, vous pouvez éventuellement définir apiKey sur une clé API Google qui autorise l’accès à l’API Web Fonts Developer. Cette clé n’est nécessaire que 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. Procédez comme suit :

    1. Ouvrez la console Google Cloud.
    2. Vérifiez si l’API Web Fonts Developer est activée. Le cas échéant, activez-la.
    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 en tant que 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 API, sélectionnez Restreindre la clé. Dans la liste déroulante, sélectionnez API Web Fonts Developer.
    7. Sélectionnez Enregistrer.

Fichier config.publish.json

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

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

Configurez le fichier :

  1. Copiez-collez les valeurs managementApiUrl et managementApiAccessToken à partir du fichier de configuration précédent.

  2. Si vous souhaitez activer CAPTCHA dans votre portail des développeurs, définissez "useHipCaptcha": true. Veillez à configurer les paramètres CORS pour le back-end du portail des développeurs.

Fichier config.runtime.json

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

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

Configurez le fichier :

  1. Copiez-collez la valeur managementApiUrl à partir du fichier de configuration précédent.

  2. Dans la valeur backendUrl, 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é Site web statique dans votre compte de stockage en fournissant les routes vers les pages d’index et d’erreur :

  1. Accédez à votre compte de stockage dans le portail Azure, puis sélectionnez Site web statique dans le menu de gauche.

  2. Dans la page Site web statique, sélectionnez Activé.

  3. Dans le champ Nom du document d’index, entrez index.html.

  4. Dans le champ Chemin du document d’erreur, entrez 404/index.html.

  5. Sélectionnez 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 :

  1. Accédez à votre compte de stockage dans le portail Azure, puis sélectionnez CORS dans le menu de gauche.

  2. Sous l’onglet Service BLOB, configurez les règles suivantes :

    Règle Value
    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

  3. Sélectionnez Enregistrer.

Configurer les paramètres CORS pour le back-end 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 des développeurs auto-hébergé. Le portail des développeurs auto-hébergé s’appuie sur le point de terminaison du back-end du portail de développement (défini dans backendUrl dans les fichiers de configuration du portail) pour activer plusieurs fonctionnalités, notamment :

Pour ajouter des paramètres CORS :

  1. Accédez à votre instance Gestion des API dans le portail Azure, puis sélectionnezPortail des développeurs> dans le menu de gauche.
  2. Sous l’onglet Configuration du portail auto-hébergé, ajoutez une ou plusieurs valeurs de domaine Origine. Par exemple :
    • Domaine où le portail auto-hébergé est hébergé, comme https://www.contoso.com
    • localhost pour le développement local (le cas échéant), comme http://localhost:8080 ou https://localhost:8080
  3. Sélectionnez Enregistrer.

Étape 3 : Exécuter le portail

Vous pouvez maintenant générer et exécuter une instance de portail locale en mode Développement. En mode Développement, toutes les optimisations sont désactivées et les mappages de source sont activés.

Exécutez la commande suivante :

npm start

Après un bref laps de temps, le navigateur par défaut s’ouvre automatiquement avec votre instance locale du portail des développeurs. L’adresse par défaut est http://localhost:8080, mais le port peut changer si 8080 est déjà occupé. Toute modification apportée à la base de code du projet déclenche une régénération et actualise la fenêtre de votre navigateur.

Étape 4 : Apporter des modifications dans l’éditeur visuel

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

  • Personnaliser votre portail
  • Créer du contenu
  • Organiser la structure du site web
  • Styliser son apparence

Pour plus d’informations, consultez Tutoriel : Accéder et personnaliser le portail des développeurs. Celui-ci aborde les bases de l’interface utilisateur d’administration, et liste les modifications qu’il est recommandé d’apporter au contenu par défaut. Enregistrez toutes les modifications dans l’environnement local, puis appuyez sur Ctrl + C pour le 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 répertoire ./dist/website :

npm run publish

Étape 6 : Charger des fichiers statiques dans un objet blob

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

  1. Ouvrez l’invite de commandes Windows, PowerShell ou une autre interface de commande.

  2. Exécutez la commande d’interface de ligne de commande Azure suivante.

    Remplacez <account-connection-string> par la chaîne de connexion de votre compte de stockage. Vous pouvez la récupérer dans 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 en ligne sous le nom d’hôte qui est spécifié dans vos propriétés de stockage Azure (Point de terminaison principal dans Sites web statiques).

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

Remplacez l’URL du portail des développeurs dans les modèles de notifications Gestion des API pour qu’elle pointe vers votre portail auto-hébergé. Consultez Configuration des notifications et des modèles de messages électroniques dans Gestion des API Azure.

Vous devez apporter les modifications suivantes aux modèles par défaut :

Notes

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

Confirmation de modification de l’adresse e-mail

Mettez à jour l’URL du portail des développeurs dans le modèle de notification Email change confirmation (Confirmation de modification de l’adresse e-mail) :

Contenu d’origine

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

Updated

<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 New developer account confirmation (Confirmation du nouveau compte de développeur) :

Contenu d’origine

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

Updated

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

Invitation de l'utilisateur

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

Contenu d’origine

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

Updated

<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 Nouvel abonnement activé :

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!

Updated

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

Updated

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>

Updated

<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>

Updated

<!--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 Password change confirmation (Confirmation du changement de mot de passe) :

Contenu d’origine

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

Updated

<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 un des modèles qui comportent un lien dans le pied de page :

Contenu d’origine

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

Updated

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

Passer du portail des développeurs managé au portail auto-hébergé

Avec le temps, les besoins de votre entreprise peuvent changer. Vous pouvez vous retrouver dans une situation où la version managée du portail des développeurs Gestion des API ne répond plus à vos besoins. Par exemple, une nouvelle exigence peut vous obliger à créer un widget personnalisé qui s’intègre à un fournisseur de données tiers. Contrairement à la version managée, la version auto-hébergée du portail vous offre une flexibilité et une extensibilité totales.

Processus de transition

Vous pouvez passer de la version managée à une version auto-hébergée au sein de la même instance du service Gestion des API. Le processus conserve les modifications que vous avez effectuées dans la version managée du portail. Veillez à sauvegarder le contenu du portail au préalable. Le script de sauvegarde se trouve dans le dossier scripts du dépôt GitHub qui se trouve sur le 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 le montrent les étapes précédentes de cet article. Il y a une exception, qui se trouve au niveau de l’étape de configuration. Le compte de stockage du fichier config.design.jsondoit être le même que celui de la version managée du portail. Pour obtenir des instructions sur la récupération de l’URL SAS, consultez Tutoriel : Utiliser une identité de VM Linux affectée par le système pour accéder au stockage Azure via des informations d’identification SAS.

Conseil

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

Étapes suivantes