Partager via

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

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

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. Le portail des développeurs nécessite que l’API REST Gestion des API gère le contenu.

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 vers une plateforme d’hébergement, éventuellement fronté par une solution telle qu’un réseau de distribution de contenu (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’un serveur géré à un fichier 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 :

Étape 1 : Configurer l’environnement local

Pour configurer votre environnement local, clonez le référentiel, basculez vers la dernière version du portail des développeurs et installez 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 à votre copie locale du dépôt :

    cd api-management-developer-portal

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

  4. 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. L’équipe de développement Gestion des API utilise 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

fichier config.design.json

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

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

Dans subscriptionId, resourceGroupNameet serviceName, entrez des valeurs pour l’abonnement, le groupe de ressources et le nom du service de votre instance Gestion des API. I

Paramètres facultatifs dans config.design.json

Si vous le souhaitez, configurez les paramètres suivants dans le config.design.json fichier :

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

    {
    ...
    "useHipCaptcha": true
    ...
}

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

    {
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}

  3. 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",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Copiez et collez les valeurs subscriptionId, resourceGroupName et serviceName du fichier de configuration précédent.

fichier config.runtime.json

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

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

Remplacez < service name > par le nom de votre instance Gestion des API utilisée dans les fichiers de configuration précédents.

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 :

  1. Dans le portail Azure, accédez à votre compte de stockage dans le portail Azure.

  2. Dans le menu de la barre latérale, sélectionnezSite web statique> données.

  3. Dans la page du site web statique , sélectionnez Activé.

  4. Dans le champ Nom du document Index , entrez index.html.

  5. Dans le champ Chemin d’accès du document d’erreur , entrez 404/index.html.

  6. Cliquez sur Enregistrer.

Notez l’URL du point de terminaison principal . Vous allez le configurer ultérieurement pour accéder à votre portail auto-hébergé.

Configurer les paramètres CORS pour le compte de stockage

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

  1. Accédez à votre compte de stockage dans le portail Azure.

  2. Dans le menu de la barre latérale, sous Paramètres, sélectionnez Partage de ressources (CORS).

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

  4. Cliquez sur Enregistrer.

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 le fichier portail config.runtime.json ) pour activer plusieurs fonctionnalités, notamment :

Pour ajouter des paramètres CORS :

  1. Accédez à votre instance Gestion des API dans le portail Azure.
  2. Dans le menu de la barre latérale, sélectionnezParamètres du > des développeurs.
  3. 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://contoso.developer.azure-api.net
    • localhost pour le développement local (le cas échéant), comme http://localhost:8080 ou https://localhost:8080
  4. 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.

  1. Exécutez la commande suivante:

    npm run start

  2. Vous êtes invité à vous authentifier via votre navigateur. Sélectionnez vos informations d’identification Microsoft pour continuer.

  3. Après un certain temps, 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é. Lorsque vous apportez des modifications à la base de code du projet, elle 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 le portail localement

  1. Exécutez npm run publish. Vous êtes invité à vous authentifier via votre navigateur. Sélectionnez vos informations d’identification Microsoft pour continuer.

  2. Après un certain temps, le contenu est publié dans le dist/website dossier.

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

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

  2. Exécutez la commande suivante az storage blog upload-batch . Remplacez <connection-string> par une chaîne de connexion pour votre compte de stockage. Vous pouvez l’obtenir à partir de la section Sécurité +> réseau de votre compte de stockage.

    az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<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. Dans le menu de la barre latérale, accédez ausite web statique> données. Le nom d’hôte est la valeur du point de terminaison principal.

Héberger l’éditeur de site web

Lorsque vous apportez des modifications dans le code du site web, vous devrez peut-être mettre à jour le code de l’éditeur de site web et prendre en charge correctement la modification de vos widgets modifiés. Dans ce cas, outre l’hébergement du portail, vous pouvez également héberger l’application de l’éditeur. Pour cela, vous devez le générer et le configurer pour accéder à votre service Gestion des API.

Pour cela, vous avez besoin d’une application Microsoft Entra ID dans votre locataire :

  1. Enregistrez une application dans votre tenant Microsoft Entra ID. Notez l’ID de l’application (client) et l’ID du répertoire (locataire). Vous les configurez ultérieurement.
  2. Configurez un URI de redirection web (URL de réponse) dans cette application pour pointer vers le point de terminaison de l’application web où le concepteur est hébergé. Il s’agit généralement de l’emplacement du site Web basé sur le stockage blob. Exemple : https://<your-storage-account-name>z13.web.core.windows.net/.
  3. Si vous souhaitez publier le portail dans des pipelines (GitHub Actions), créez également une clé secrète client pour cette application. Notez la valeur secrète générée et stockez-la dans un emplacement sûr.

Ensuite, procédez comme suit pour héberger l’éditeur de site web :

  1. Ajoutez clientId et tenantId champs au config.design.json fichier.

    {
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

  2. Exécutez la commande npm run build-designer pour générer le concepteur.

  3. Accédez au dossier généré /dist/designer , qui contient un fichier config.json avec le contenu suivant :

    {
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

  4. Vérifiez la configuration de subscriptionId, resourceGroupName et serviceName, qui sont nécessaires pour vous connecter à votre service Gestion des API à l’aide des API Azure Resource Manager.

Publier le portail dans les pipelines (GitHub Actions)

Vous pouvez publier le portail auto-hébergé dans un pipeline tel que GitHub Actions.

Le pipeline a également besoin des informations d’identification de l’application Entra ID pour exécuter la publication à l’aide de pipelines. Vous pouvez utiliser la même application Entra ID décrite dans les étapes précédentes. Le tenantId, clientId, et en particulier clientSecret doivent être conservés dans leurs stockages de clés respectifs. Pour plus d’informations , consultez Utilisation des secrets dans GitHub Actions .

Exemple de pipeline GitHub Actions YAML :


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

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 afin qu’elle pointe 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>

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 de 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 de l’utilisateur Inviter :

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

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 de confirmation de modification 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 n’importe quel modèle qui a 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 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.v3 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.

Contenu connexe

  • Last updated on