Comment enregistrer et configurer votre configuration du service Gestion des API à l’aide de Git

Article
05/12/2023

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

Chaque instance du service Gestion des API gère une base de données de configuration qui contient des informations sur la configuration et les métadonnées de cette instance de service. Des modifications peuvent être apportées à l’instance de service en changeant un paramètre dans le portail Azure, en utilisant des outils Azure tels qu’Azure PowerShell ou Azure CLI, ou en effectuant un appel d’API REST. Outre ces méthodes, vous pouvez gérer votre configuration d’instance de service à l’aide de Git, notamment dans le cadre des scénarios suivants :

Contrôle de version de la configuration : téléchargez et stockez différentes versions de votre configuration de service
Modifications en bloc de la configuration : apportez des modifications à plusieurs parties de votre configuration de service dans votre dépôt local et intégrez les modifications au serveur en une seule opération
Chaîne d’outils et flux de travail Git familiers : utilisez les flux de travail et les outils Git qui vous sont déjà familiers

Le diagramme suivant montre une vue d’ensemble des différentes façons de configurer votre instance du service Gestion des API.

Diagramme qui compare les façons de configurer la gestion des API Azure.

Lorsque vous apportez des modifications à votre service à l’aide du portail Azure, d’outils Azure tels qu’Azure PowerShell ou Azure CLI, ou d’API REST, vous gérez la base de données de configuration de votre service à l’aide du point de terminaison https://{name}.management.azure-api.net, comme indiqué sur le côté droit du schéma. Le côté gauche du diagramme illustre comment vous pouvez gérer votre configuration de service à l’aide de Git et du dépôt Git pour votre service situé à l’adresse https://{name}.scm.azure-api.net.

Les étapes suivantes fournissent une vue d’ensemble de la gestion de votre instance du service Gestion des API à l’aide de Git.

Accéder à la configuration de Git dans votre service
Enregistrer votre base de données de configuration de service dans votre dépôt Git
Cloner le dépôt Git sur votre ordinateur local
Récupérer le dernier dépôt sur votre ordinateur local, puis valider les modifications et les transférer vers votre dépôt
Déployer les modifications depuis votre dépôt dans votre base de données de configuration de service

Cet article décrit comment activer et utiliser Git pour gérer votre configuration de service et fournit une référence pour les fichiers et dossiers dans le dépôt Git.

Important

Cette fonctionnalité est conçue pour fonctionner avec des configurations de service Gestion des API de taille petite à moyenne, comme celles dont la taille exportée est inférieure à 10 Mo ou avec moins de 10 000 entités. Les services comportant un grand nombre d’entités (produits, API, opérations, schémas, etc.) peuvent connaître des échecs inattendus lors du traitement des commandes Git. Si vous rencontrez de telles défaillances, réduisez la taille de la configuration de votre service, puis réessayez. Contactez le support Azure si vous avez besoin d’aide.

Accéder à la configuration de Git dans votre service

Accédez à votre instance APIM dans le portail Azure.
Dans le menu de gauche, sous Déploiement et infrastructure, sélectionnez Référentiel.

Capture d’écran montrant comment accéder à la configuration de Git pour la gestion des API.

Enregistrer la configuration du service dans le dépôt Git

Attention

Les secrets qui ne sont pas définis comme valeurs nommées sont stockés dans le dépôt et restent dans son historique. Les valeurs nommées offrent un emplacement sécurisé pour gérer les valeurs de chaîne constante, notamment les secrets, dans toutes les stratégies et configurations d’API ; vous n’êtes donc pas obligé de les stocker directement dans les déclarations de votre stratégie. Pour plus d’informations, consultez Utiliser des valeurs nommées dans les stratégies Gestion des API Azure.

Avant le clonage du référentiel, enregistrez l’état actuel de la configuration du service dans le référentiel.

Dans la page Référentiel, sélectionnez Enregistrer dans le référentiel.
Apportez les modifications souhaitées à l’écran de confirmation, comme le nom de la branche, pour enregistrer la configuration, puis sélectionnez Enregistrer.

Après quelques instants, la configuration est enregistrée, et l’état de configuration du dépôt est affiché, y compris la date et l’heure de la dernière modification de la configuration et de la dernière synchronisation entre la configuration du service et le dépôt.

Une fois la configuration enregistrée dans le dépôt, elle peut être clonée.

Pour plus d’informations sur l’enregistrement de la configuration du service à l’aide de l’API REST, consultez Configuration du locataire - Enregistrer.

Obtenir les informations d’identification

Pour cloner un référentiel, en plus de l’URL de votre référentiel, vous avez besoin d’un nom d’utilisateur et d’un mot de passe.

Dans la page Référentiel, sélectionnez Informations d’identification d’accès en haut de la page.
Notez le nom d’utilisateur fourni dans la page Informations d’identification d’accès.
Pour générer un mot de passe, vérifiez d’abord que le champ Expiration est défini sur la date et l’heure d’expiration souhaitées, puis sélectionnez Générer.

Important

Notez ce mot de passe. Une fois que vous quittez cette page, le mot de passe ne s’affiche plus.

Clonez le référentiel sur votre ordinateur local.

Les exemples suivants utilisent l’outil Git Bash de Git pour Windows , mais vous pouvez utiliser n’importe quel outil Git auquel vous êtes habitué.

Ouvrez votre outil Git dans le dossier de votre choix et exécutez la commande suivante pour cloner le référentiel Git sur votre ordinateur local, à l’aide de la commande suivante :

git clone https://{name}.scm.azure-api.net/

Quand vous y êtes invité, fournissez le nom d’utilisateur et le mot de passe.

En cas d’erreur, essayez de modifier votre commande git clone pour y inclure le nom d’utilisateur et le mot de passe, comme illustré dans l’exemple suivant.

git clone https://username:password@{name}.scm.azure-api.net/

En cas d’erreur, essayez d’appliquer un encodage URL à la partie mot de passe de la commande. Pour effectuer cette opération rapidement, vous pouvez ouvrir Visual Studio et exécuter la commande ci-dessous dans la Fenêtre Exécution. Pour ouvrir la Fenêtre Exécution, ouvrez une solution ou un projet dans Visual Studio (ou créez une application console vide), puis choisissez Fenêtres, Exécution dans le menu Déboguer.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

Pour construire la commande git, utilisez le mot de passe codé, avec votre nom d’utilisateur et l’emplacement du dépôt.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

Une fois le clonage terminé, remplacez le répertoire par votre référentiel en exécutant une commande comme la suivante.

cd {name}.scm.azure-api.net/

Si vous avez enregistré la configuration dans une branche autre que la branche par défaut (master), extrayez la branche :

git checkout <branch_name>

Une fois le référentiel cloné, vous pouvez l’afficher et l’utiliser dans votre système de fichiers local. Pour plus d’informations, consultez Référence de la structure des fichiers et des dossiers du dépôt Git local.

Mettre à jour votre dépôt local avec la dernière configuration de l’instance du service

Si vous apportez des changements à votre instance de service Gestion des API dans le portail Azure ou à l’aide d’outils Azure, vous devez enregistrer ces changements dans le dépôt pour pouvoir mettre à jour votre dépôt local avec les derniers changements.

Pour enregistrer les modifications à l’aide du portail Azure, sélectionnez Enregistrer dans le référentiel sous l’onglet Référentiel de votre instance Gestion des API.

Ensuite, pour mettre à jour votre référentiel local :

Vérifiez que vous vous trouvez dans le dossier de votre dépôt local. Si vous venez d’exécuter la commande git clone , vous devez accéder au répertoire de votre dépôt en exécutant une commande semblable à la suivante.
```
cd {name}.scm.azure-api.net/
```
Dans le dossier de votre référentiel local, exécutez la commande suivante.
```
git pull
```

Transférer les modifications depuis votre dépôt local vers le dépôt du serveur

Pour transférer les modifications depuis votre dépôt local vers le dépôt du serveur, vous devez valider vos modifications, puis les transférer vers le dépôt du serveur. Pour valider vos modifications, ouvrez votre outil de commande Git, accédez au répertoire de votre dépôt local et exécutez les commandes suivantes.

git add --all
git commit -m "Description of your changes"

Pour transférer toutes les validations vers le serveur, exécutez la commande suivante.

git push

Déployer les modifications de configuration de service sur l’instance du service Gestion des API

Une fois vos modifications locales validées et transférées vers le dépôt du serveur, vous pouvez les déployer sur votre instance du service Gestion des API.

Accédez à votre instance APIM dans le portail Azure.
Dans le menu de gauche, sous Déploiement et infrastructure, sélectionnez Référentiel>Déployer sur Gestion des API.
Dans la page de Déployer la configuration du référentiel, entrez le nom de la branche contenant les modifications de configuration souhaitées, puis sélectionnez éventuellement Supprimer les abonnements des produits supprimés. Sélectionnez Enregistrer.

Pour plus d’informations sur l’exécution de cette opération à l’aide de l’API REST, consultez Configuration du locataire - Déployer.

Référence de la structure des fichiers et des dossiers du dépôt Git local

Les fichiers et dossiers figurant dans le référentiel Git local contiennent les informations de configuration relatives à l'instance de service.

Élément	Description
Dossier api-management racine	Contient la configuration de niveau supérieur pour l’instance de service
Dossier apiReleases	Contient la configuration des versions d’API dans l’instance de service
Dossier apis	Contient la configuration des API dans l’instance de service
Dossier apiVersionSets	Contient la configuration des jeux de versions d’API dans l’instance de service
Dossier backends	Contient la configuration des ressources de back-end dans l’instance de service
Dossier groups	Contient la configuration des groupes dans l’instance de service
Dossier policies	Contient les stratégies dans l’instance de service
Dossier portalStyles	Contient la configuration des personnalisations du portail des développeurs dans l’instance de service
Dossier portalTemplates	Contient la configuration des modèles du portail des développeurs dans l’instance de service
Dossier products	Contient la configuration des produits dans l’instance de service
Dossier templates	Contient la configuration des modèles d’e-mail dans l’instance de service

Chaque dossier peut contenir un ou plusieurs fichiers et, dans certains cas, un ou plusieurs dossiers, par exemple un dossier par API, produit ou groupe. Les fichiers dans chaque dossier sont spécifiques du type d’entité décrit par le nom du dossier.

Type de fichier	Objectif
json	Informations de configuration sur l’entité concernée
html	Descriptions de l’entité, souvent affichées dans le portail des développeurs
Xml	Policy statements
css	Feuilles de style pour la personnalisation du portail des développeurs

Ces fichiers peuvent être créés, supprimés, modifiés et gérés dans votre système de fichiers local, et les modifications peuvent être redéployées sur votre instance du service Gestion des API.

Notes

Les entités suivantes ne se trouvent pas dans le dépôt Git et ne peuvent pas être configurées à l’aide de Git.

Utilisateurs
Abonnements
Valeurs nommées
Entités du portail des développeurs autres que les styles et modèles
Fragments de stratégie

Dossier api-management racine

Le dossier api-management racine contient un fichier configuration.json qui renferme des informations de premier niveau sur l’instance de service dans le format suivant.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

Les quatre premiers paramètres (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled et UserRegistrationTermsConsentRequired) correspondent aux paramètres suivants, disponibles dans l’onglet Identités de la section Portail des développeurs.

Paramètre d’identité	Correspond à
RegistrationEnabled	Présence du fournisseur d’identité Nom d’utilisateur et mot de passe
UserRegistrationTerms	Conditions d’utilisation liées à l’inscription de l’utilisateur
UserRegistrationTermsEnabled	Afficher les conditions d’utilisation dans la page d’abonnement
UserRegistrationTermsConsentRequired	Exiger le consentement
RequireUserSigninEnabled	Rediriger les utilisateurs anonymes vers la page de connexion

Les quatre paramètres qui suivent (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled et DelegationValidationKey) correspondent aux paramètres suivants, disponibles dans l’onglet Délégation de la section Portail des développeurs.

Paramètre de délégation	Correspond à
DelegationEnabled	Case à cocher Déléguer la connexion et l’inscription
DelegationUrl	URL de point de terminaison de la délégation
DelegatedSubscriptionEnabled	Déléguer l’abonnement au produit
DelegationValidationKey	Déléguer la clé de validation

Le dernier paramètre, $ref-policy, correspond au fichier d’instructions de stratégie globale pour l’instance de service.

Dossier apiReleases

Le dossier apiReleases contient un dossier pour chaque version d’API déployée sur une API de production et contient les éléments suivants.

apiReleases\<api release Id>\configuration.json - Configuration de la version, contenant des informations sur les dates de publication. Vous pouvez obtenir les mêmes informations en appelant l’opération Obtenir une version spécifique.

Dossier apis

Le dossier apis contient un dossier pour chaque API dans l’instance de service, qui renferme les éléments suivants.

apis\<api name>\configuration.json : Configuration pour l’API, contenant des informations sur l’URL du service de back-end et les opérations. Vous pouvez obtenir les mêmes informations en appelant l’opération Obtenir une API spécifique.
apis\<api name>\api.description.html - Description de l’API, correspondant à la propriété description de l’entité d’API dans l’API REST.
apis\<api name>\operations\ : Dossier contenant des fichiers <operation name>.description.html qui correspondent aux opérations de l’API. Chaque fichier contient la description d’une opération unique dans l’API, qui correspond à la propriété description de l’entité Operation dans l’API REST.

Dossier apiVersionSets

Le dossier apiVersionSets contient un dossier pour chaque ensemble de versions d’API créé pour une API et contient les éléments suivants.

apiVersionSets\<api version set Id>\configuration.json - Configuration pour le jeu de versions. Vous pouvez obtenir les mêmes informations en appelant l’opération Obtenir un jeu de versions spécifique.

Dossier groups

Le dossier groups contient un dossier pour chaque groupe défini dans l’instance de service.

groups\<group name>\configuration.json - Configuration pour le groupe. Vous pouvez obtenir les mêmes informations en appelant l’opération Obtenir un groupe spécifique .
groups\<group name>\description.html : Description du groupe, correspondant à la propriété description de l’entité de groupe.

Dossier policies

Le dossier policies contient les instructions de stratégie pour votre instance de service.

policies\global.xml : Stratégies définies dans l’étendue globale de votre instance de service.
policies\apis\<api name>\ : Si vous avez des stratégies définies à l’échelle de l’API, elles se trouvent dans ce dossier.
policies\apis\<api name>\<operation name>\ : Si des stratégies sont définies à l’échelle des opérations, elles se trouvent dans ce dossier, qui contient des fichiers <operation name>.xml correspondant aux instructions de stratégie pour chaque opération.
policies\products\ : Si des stratégies sont définies à l’échelle des produits, elles se trouvent dans ce dossier, qui contient des fichiers <product name>.xml correspondant aux instructions de stratégie pour chaque produit.

Dossier portalStyles

Le dossier portalStyles contient des feuilles de configuration et de style pour la personnalisation du portail du développeur de l’instance de service, désormais obsolète.

portalStyles\configuration.json : contient les noms des feuilles de style utilisées par le portail des développeurs
portalStyles\<style name>.css : chaque fichier <style name>.css contient des styles pour le portail des développeurs (Preview.css et Production.css par défaut).

Dossier portalTemplates

Le dossier portalTemplates contient des modèles pour personnaliser le portail des développeurs déconseillé de l’instance de service.

portalTemplates\<template name>\configuration.json - Configuration du modèle.
portalTemplates\<template name>\<page name>.html - Pages HTML d’origine et modifiées du modèle.

Dossier products

Le dossier products contient un dossier pour chaque produit défini dans l’instance de service.

products\<product name>\configuration.json : Configuration du produit. Vous pouvez obtenir les mêmes informations en appelant l’opération Obtenir un produit spécifique .
products\<product name>\product.description.html : Description du produit, correspond à la propriété description de l’entité produit dans l’API REST.

modèles

Le dossier templates contient la configuration des modèles d’e-mail dans l’instance de service.

<template name>\configuration.json : Configuration du modèle d’e-mail.
<template name>\body.html : Corps du modèle d’e-mail.

Étapes suivantes

Pour plus d’informations sur d’autres méthodes pour gérer votre instance de service, consultez les sources suivantes :

Partager via