Partager via

Appeler des vérifications de la fonction Azure/API REST

  • Article

Les vérifications d’appel de fonction Azure/d’API REST vous permettent d’écrire du code pour décider si une phase de pipeline spécifique est autorisée à accéder à une ressource protégée ou non. Ces vérifications peuvent s’exécuter en deux modes :

  • Asynchrone (recommandé) : mode envoi, dans lequel Azure DevOps attend que l’implémentation de fonction Azure/d’API REST rappelle Azure DevOps avec une décision d’accès par phase
  • Synchrone : mode d’interrogation, dans lequel Azure DevOps appelle régulièrement la fonction Azure/l’API REST pour obtenir une décision d’accès par phase

Dans le reste de ce guide, nous faisons simplement référence aux vérifications des fonctions Azure/API REST sous le nom de « vérifications ».

La méthode recommandée pour utiliser les vérifications est en mode asynchrone. Ce mode vous offre le plus haut niveau de contrôle sur la logique de vérification, permet de raisonner facilement l’état dans lequel se trouve le système et dissocie Azure Pipelines de votre implémentation de vérifications, offrant ainsi la meilleure scalabilité. Toutes les vérifications synchrones peuvent être implémentées à l’aide du mode de vérification asynchrone.

Vérifications asynchrones

En mode asynchrone, Azure DevOps effectue un appel à la vérification de fonction Azure/d’API REST et attend un rappel avec la décision d’accès aux ressources. Il n’existe aucune connexion HTTP ouverte entre Azure DevOps et votre implémentation de vérification pendant la période d’attente.

Le reste de cette section traite des vérifications de fonction Azure, mais sauf indication contraire, les instructions s’appliquent également aux vérifications d’appel d’API REST.

Le mode asynchrone recommandé comprend deux étapes de communication :

  1. Fournissez la charge utile de vérification. Azure Pipelines effectue un appel HTTP à votre fonction Azure/API REST uniquement pour fournir la charge utile de vérification et non pour recevoir une décision sur place. Votre fonction doit simplement accuser réception des informations et mettre fin à la connexion HTTP avec Azure DevOps. Votre implémentation de vérification doit traiter la requête HTTP dans les 3 secondes.
  2. Fournir la décision d’accès par le biais d’un rappel. Votre vérification doit s’exécuter de manière asynchrone, et évaluer la condition nécessaire au pipeline pour accéder à la ressource protégée (en effectuant éventuellement plusieurs évaluations à différents moments dans le temps). Une fois la décision finale prise, votre fonction Azure effectue un appel HTTP REST dans Azure DevOps pour communiquer la décision. À tout moment, il doit y avoir une connexion HTTP ouverte unique entre Azure DevOps et votre implémentation de vérification. Cela permet d’économiser des ressources du côté de votre fonction Azure et du côté d’Azure Pipelines.

Si une vérification réussit, le pipeline est autorisé à accéder à une ressource protégée, et un déploiement intermédiaire peut continuer. Si une vérification échoue, la phase échoue. S’il y a plusieurs vérifications en une seule phase, toutes doivent réussir avant que l’accès aux ressources protégées soit autorisé, mais une seule défaillance suffit pour faire échouer la phase.

L’implémentation recommandée du mode asynchrone pour une seule vérification de fonction Azure est illustrée dans le diagramme suivant.

Diagramme montrant l’implémentation recommandée du mode asynchrone pour une seule vérification de fonction Azure.

Les étapes du diagramme sont les suivantes :

  1. Vérifier la remise. Azure Pipelines prépare le déploiement d’une phase de pipeline et nécessite l’accès à une ressource protégée. Il appelle la vérification de fonction Azure correspondante et attend la confirmation de réception, l’appel se terminant par un code d’état HTTP 200. Le déploiement de la phase est suspendu en attendant une décision.
  2. Vérifier l’évaluation. Cette étape se produit à l’intérieur de votre implémentation Azure Function, qui s’exécute sur vos propres ressources Azure et dont le code est entièrement sous votre contrôle. Nous vous recommandons d’effectuer les étapes suivantes pour votre Azure Function :
    • 2.1 Démarrer une tâche asynchrone et retourner le code d’état HTTP200
    • 2.2 Entrer dans une boucle interne dans laquelle elle peut effectuer plusieurs évaluations de condition
    • 2.3 Évaluer les conditions d’accès
    • 2.4 Si aucune décision finale ne peut être prise, replanifiez une réévaluation des conditions pour un point ultérieur, puis passez à l’étape 2.3
  3. Communication de la décision. La fonction Azure rappelle Azure Pipelines avec la décision d’accès. Le déploiement de la phase peut se poursuivre

Lorsque vous utilisez la mise en œuvre recommandée, la page des détails de l’exécution de pipeline affiche le dernier journal de contrôle.

Capture d’écran des détails de l’exécution du pipeline avec des informations de vérification.

Dans le panneau de configuration de vérification de la fonction Azure/de l’API REST, assurez-vous de :

  • Rappel sélectionné pour l’Événement d’achèvement
  • Définissez Temps entre les évaluations (minutes) sur 0

La définition de la Durée entre les évaluations sur une valeur non nulle signifie que la décision de vérification (réussite/échec) n’est pas finale. La vérification est réévaluée jusqu’à ce que toutes les autres approbations et vérifications atteignent un état final.

Transmettre les informations d’exécution de pipeline aux vérifications

Lors de la configuration de la vérification, vous pouvez spécifier les informations d’exécution du pipeline que vous souhaitez envoyer à votre vérification. Au minimum, vous devez envoyer :

  • "PlanUrl": "$(system.CollectionUri)"
  • "ProjectId": "$(system.TeamProjectId)"
  • "HubName": "$(system.HostType)"
  • "PlanId": "$(system.PlanId)"
  • "JobId": "$(system.JobId)"
  • "TaskInstanceId": "$(system.TaskInstanceId)"
  • "AuthToken": "$(system.AccessToken)"

Ces paires clé-valeur sont définies, par défaut, dans le Headers de l’appel REST effectué par Azure Pipelines.

Vous devez utiliser AuthToken pour effectuer des appels dans Azure DevOps, par exemple lorsque votre vérification renvoie une décision.

Appeler Azure DevOps

Pour prendre une décision, votre vérification peut avoir besoin d’informations sur l’exécution actuelle du pipeline qui ne peut pas être passée à la vérification, de sorte que la vérification doit la récupérer. Imaginez que votre vérification vérifie qu’une exécution de pipeline a exécuté une tâche particulière, par exemple une tâche d’analyse statique. Votre vérification doit appeler Azure DevOps et obtenir la liste des tâches déjà exécutées.

Pour appeler Azure DevOps, nous vous recommandons d’utiliser le jeton d’accès de tâche émis pour l’exécution de la vérification, au lieu d’un jeton d’accès personnel (PAT). Le jeton est déjà fourni à vos vérifications par défaut, dans l’en-tête AuthToken.

Comparé aux PAT, le jeton d’accès de travail est moins susceptible d’être limité, n’a pas besoin d’actualisation manuelle et n’est pas lié à un compte personnel. Le jeton reste valide pendant 48 heures.

L’utilisation du jeton d’accès de travail élimine tous les problèmes de limitation de l’API REST Azure DevOps. Lorsque vous utilisez un PAT, vous utilisez le même PAT pour toutes les exécutions de votre pipeline. Si vous exécutez un grand nombre de pipelines, le PAT est limité. Il s’agit moins d’un problème avec le jeton d’accès au travail, car un nouveau jeton est généré pour chaque exécution de vérification.

Le jeton est émis pour l’identité de build utilisée pour exécuter un pipeline, par exemple, le service de build FabrikamFiberChat (FabrikamFiber). En d’autres termes, le jeton peut être utilisé pour accéder aux mêmes dépôts ou exécutions de pipeline que le pipeline hôte. Si vous avez activé Protéger l’accès aux dépôts dans les pipelines YAML, son étendue est limitée uniquement aux dépôts référencés dans l’exécution du pipeline.

Si votre vérification doit accéder à des ressources non liées aux pipelines, par exemple, les récits utilisateur Boards, vous devez accorder ces autorisations aux identités de build des pipelines. Si votre vérification peut être déclenchée à partir de plusieurs projets, assurez-vous que tous les pipelines de tous les projets peuvent accéder aux ressources requises.

Renvoyer une décision à Azure DevOps

Votre implémentation de vérification doit utiliser l’appel d’API REST Post Event pour communiquer une décision à Azure Pipelines. Veillez à spécifier les propriétés suivantes :

  • Headers: Bearer {AuthToken}
  • Body:
{
    "name": "TaskCompleted",
    "taskId": "{TaskInstanceId}",
    "jobId": "{JobId}",
    "result": "succeeded|failed"
}

Envoyer les mises à jour d’état à Azure DevOps à partir des vérifications

Vous pouvez fournir des mises à jour d’état aux utilisateurs d’Azure Pipelines à partir de vos vérifications à l’aide des API REST Azure Pipelines. Cette fonctionnalité est utile, par exemple, si vous souhaitez informer les utilisateurs que la vérification attend une action externe, par exemple si quelqu’un doit approuver un ticket ServiceNow.

Les étapes d’envoi des mises à jour d’état sont les suivantes :

  1. Créer un journal des tâches
  2. Ajouter au journal des tâches
  3. Mettre à jour l’enregistrement de chronologie

Tous les appels d’API REST doivent être authentifiés.

Exemples

Vérification de fonction Azure de base

Dans cet exemple de base, la fonction Azure vérifie que l’exécution du pipeline appelant a exécuté une tâche CmdLine, avant de lui accorder l’accès à une ressource protégée.

La fonction Azure passe par les étapes suivantes :

  1. Confirme la réception de la charge utile de vérification
  2. Envoie une mise à jour d’état à Azure Pipelines pour indiquer que la vérification a démarré
  3. Utilise {AuthToken} pour effectuer un rappel dans Azure Pipelines pour récupérer l’entrée Chronologie de l’exécution du pipeline
  4. Vérifie si la chronologie contient une tâche avec "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (ID de la tâche CmdLine)
  5. Envoie une mise à jour d’état avec le résultat de la recherche
  6. Envoie une décision de vérification à Azure Pipelines

Vous pouvez télécharger cet exemple à partir de GitHub.

Pour utiliser cette vérification de fonction Azure, vous devez spécifier les Headers comme suit lors de la configuration de la vérification :

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

Vérification avancée de fonction Azure

Dans cet exemple avancé, la fonction Azure vérifie que l’élément de travail Azure Boards référencé dans le message de validation qui a déclenché l’exécution du pipeline est dans le bon état.

La fonction Azure passe par les étapes suivantes :

  1. Confirme la réception de la charge utile de vérification
  2. Envoie une mise à jour d’état à Azure Pipelines pour indiquer que la vérification a démarré
  3. Utilise {AuthToken} pour effectuer un rappel dans Azure Pipelines afin de récupérer l’état de l’élément de travail Azure Boards référencé dans le message de validation qui a déclenché l’exécution du pipeline
  4. Vérifie si l’élément de travail est dans l’état Completed
  5. Envoie une mise à jour d’état avec le résultat de la vérification
  6. Si l’élément de travail n’est pas dans l’état Completed, une autre évaluation est replanifiée après 1 minute
  7. Une fois que l’élément de travail est dans le bon état, il envoie une décision positive à Azure Pipelines

Vous pouvez télécharger cet exemple à partir de GitHub.

Pour utiliser cette vérification de fonction Azure, vous devez spécifier les Headers comme suit lors de la configuration de la vérification :

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

Gestion des erreurs

Actuellement, Azure Pipelines évalue une même instance de vérification au plus 2 000 fois.

Si votre vérification ne revient pas dans Azure Pipelines dans le délai d’expiration configuré, la phase associée est ignorée. Les phases qui en dépendent sont également ignorées.

Vérifications synchrones

En mode synchrone, Azure DevOps effectue un appel à la vérification de la fonction Azure/de l’API REST pour obtenir une décision immédiate, que l’accès à une ressource protégée soit autorisé ou non.

L’implémentation du mode synchrone pour une seule vérification de fonction Azure est illustrée dans le diagramme suivant.

Diagramme montrant l’implémentation du mode synchrone pour une seule vérification de fonction Azure.

Les étapes à suivre sont les suivantes :

  1. Azure Pipelines prépare le déploiement d’une phase de pipeline et nécessite l’accès à une ressource protégée
  2. Il entre dans une boucle interne dans laquelle :
  • 2.1. Azure Pipelines appelle la vérification de fonction Azure correspondante et attend une décision
  • 2.2. Votre fonction Azure évalue les conditions nécessaires pour autoriser l’accès et retourne une décision
  • 2.3. Si le corps de réponse de la fonction Azure ne répond pas aux critères de réussite que vous avez défini, et que le Temps entre les évaluations n’est pas de zéro, Azure Pipelines replanifie une autre évaluation de vérification après le Temps entre les évaluations

Configurer les vérifications synchrones

Pour utiliser le mode synchrone pour la fonction Azure/l’API REST, dans le panneau de configuration de vérification, assurez-vous d’avoir :

  • ApiResponse sélectionnée pour l’Événement d’achèvement sous Avancé
  • Spécifié les critères de réussite qui définissent quand faire réussir la vérification en fonction du corps de la réponse de la vérification
  • Définissez Temps entre les évaluations sur 0 sous Options de contrôle
  • Définissez Délai d’expiration sur la durée pendant laquelle vous souhaitez attendre qu’une vérification réussisse. Si aucune décision positive n’est prise et que le délai d’expiration est atteint, la phase de pipeline correspondante est ignorée

Le paramètre Temps entre les évaluations définit la durée pendant laquelle la décision de la vérification est valide. La valeur 0 signifie que la décision est finale. Une valeur non nulle signifie que la vérification sera retentée après l’intervalle configuré, lorsque sa décision est négative. Lorsque plusieurs approbations et vérifications sont en cours d’exécution, la vérification est retentée indépendamment de la décision.

Le nombre maximal d’évaluations est défini par le rapport entre les valeurs Délai d’expiration et Temps entre les évaluations. Nous vous recommandons de vous assurer que ce ratio est au maximum de 10.

Transmettre les informations d’exécution de pipeline aux vérifications

Lors de la configuration de la vérification, vous pouvez spécifier les informations d’exécution du pipeline que vous souhaitez envoyer à votre vérification de fonction Azure/d’API REST. Par défaut, Azure Pipeline ajoute les informations suivantes dans le Headers de l’appel HTTP qu’il effectue.

  • "PlanUrl": "$(system.CollectionUri)"
  • "ProjectId": "$(system.TeamProjectId)"
  • "HubName": "$(system.HostType)"
  • "PlanId": "$(system.PlanId)"
  • "JobId": "$(system.JobId)"
  • "TaskInstanceId": "$(system.TaskInstanceId)"
  • "AuthToken": "$(system.AccessToken)"

Nous vous déconseillons d’effectuer des appels dans Azure DevOps en mode synchrone, car cela entraînera probablement l’échec, étant donné que votre vérification prendra plus de 3 secondes pour répondre.

Gestion des erreurs

Actuellement, Azure Pipelines évalue une même instance de vérification au plus 2 000 fois.

Quand utiliser les vérifications asynchrones ou synchrones

Examinons quelques exemples de cas d’usage et quels sont les types de vérifications recommandés à utiliser.

Les informations externes doivent être correctes

Supposons que vous disposez d’une connexion de service à une ressource de production et que vous souhaitez vous assurer que l’accès à celle-ci est autorisé uniquement si les informations contenues dans un ticket ServiceNow sont correctes. Dans ce cas, le déroulement se présente comme suit :

  • Vous ajoutez une vérification asynchrone de fonction Azure qui vérifie la justesse du ticket ServiceNow
  • Lorsqu’un pipeline qui souhaite utiliser la connexion de service s’exécute :
    • Azure Pipelines appelle votre fonction de vérification
    • Si les informations sont incorrectes, la vérification retourne une décision négative. Supposons ce résultat
    • La phase de pipeline échoue.
    • Vous mettez à jour les informations dans le ticket ServiceNow
    • Vous redémarrez la phase ayant échoué
    • La vérification s’exécute à nouveau, et cette fois-ci, elle réussit
    • L’exécution du pipeline continue

L’approbation externe doit être accordée

Supposons que vous disposez d’une connexion de service à une ressource de production et que vous souhaitez vous assurer que l’accès à celle-ci n’est autorisé qu’après qu’un administrateur a approuvé un ticket ServiceNow. Dans ce cas, le déroulement se présente comme suit :

  • Vous ajoutez une vérification asynchrone de fonction Azure qui vérifie que le ticket ServiceNow a été approuvé
  • Lorsqu’un pipeline qui souhaite utiliser la connexion de service s’exécute :
    • Azure Pipelines appelle votre fonction de vérification.
    • Si le ticket ServiceNow n’est pas approuvé, la fonction Azure envoie une mise à jour à Azure Pipelines et se replanifie pour vérifier l’état du ticket après 15 minutes
    • Une fois le ticket approuvé, la vérification revient dans Azure Pipelines avec une décision positive
    • L’exécution du pipeline continue

Le processus de développement a été suivi

Supposons que vous disposez d’une connexion de service à une ressource de production et que vous souhaitez vous assurer que l’accès à celle-ci n’est autorisé que si la couverture du code est supérieure à 80 %. Dans ce cas, le déroulement se présente comme suit :

  • Vous écrivez votre pipeline de telle sorte que les échecs de phase entraînent l’échec de la build
  • Vous ajoutez une vérification asynchrone de fonction Azure qui vérifie la couverture du code pour l’exécution du pipeline associé
  • Lorsqu’un pipeline qui souhaite utiliser la connexion de service s’exécute :
    • Azure Pipelines appelle votre fonction de vérification
    • Si la condition de couverture du code n’est pas remplie, la vérification retourne une décision négative. Supposons ce résultat
    • L’échec de la vérification entraîne l’échec de votre phase, ce qui entraîne l’échec de votre exécution de pipeline
  • L’équipe d’ingénierie ajoute les tests unitaires nécessaires pour atteindre une couverture du code de 80 %
  • Une nouvelle exécution de pipeline est déclenchée et, cette fois, la vérification passe
    • L’exécution du pipeline continue

Les critères de performances doivent être respectés

Supposons que vous déployiez de nouvelles versions de votre système en plusieurs étapes, en commençant par un déploiement canary. Vous souhaitez vous assurer que les performances de votre déploiement canary sont adéquates. Dans ce cas, le déroulement se présente comme suit :

  • Vous ajoutez une vérification asynchrone de fonction Azure
  • Lorsqu’un pipeline qui souhaite utiliser la connexion de service s’exécute :
    • Azure Pipelines appelle votre fonction de vérification
    • La vérification démarre un moniteur des performances du déploiement canary
    • La vérification planifie plusieurs points de contrôle d’évaluation pour voir comment les performances ont évolué
    • Une fois que vous avez suffisamment confiance dans les performances du déploiement canary, votre fonction Azure rappelle Azure Pipelines avec une décision positive
    • L’exécution du pipeline continue

Le motif du déploiement doit être valide

Supposons que vous disposez d’une connexion de service à une ressource d’environnement de production et que vous souhaitez vous assurer que l’accès à celle-ci se produit uniquement pour les builds mises en file d’attente manuellement. Dans ce cas, le déroulement se présente comme suit :

  • Vous ajoutez une vérification synchrone de fonction Azure qui vérifie que Build.Reason pour l’exécution de pipeline est Manual
  • Vous configurez la vérification de fonction Azure pour passer Build.Reason dans son Headers
  • Vous définissez le Temps entre les évaluations de la vérification sur 0, pour que le résultat d’échec ou de réussite soit final et qu’aucune réévaluation ne soit nécessaire
  • Lorsqu’un pipeline qui souhaite utiliser la connexion de service s’exécute :
    • Azure Pipelines appelle votre fonction de vérification
    • Si la raison est autre que Manual, la vérification échoue et l’exécution du pipeline échoue

Vérifier la conformité

Les vérifications d’invocation d’Azure Function et d’API REST incluent désormais des règles pour correspondre à l’utilisation recommandée. Les vérifications doivent suivre les règles suivantes en fonction du mode et du nombre de tentatives :

  • Vérifications asynchrones (mode rappel) : Azure Pipelines ne relance pas les vérifications asynchrones. Vous devez fournir un résultat de façon asynchrone lorsqu’une évaluation est finale. Pour que les vérifications asynchrones soient considérées comme conformes, l’intervalle de temps entre les évaluations doit être 0.

  • Vérifications synchrones (mode ApiResponse) : le nombre maximal de nouvelles tentatives pour votre vérification est de 10. Vous pouvez le faire de plusieurs façons. Par exemple, vous pouvez configurer le délai d’expiration à 20 et l’intervalle de temps entre les évaluations à 2. Vous pouvez également configurer le délai d’expiration à 100 et l’intervalle de temps entre les évaluations à 10. Toutefois, si vous configurez le délai d’expiration à 100 et définissez l’intervalle de temps entre les évaluations à 2, votre vérification ne sera pas conforme, car vous demandez 50 nouvelles tentatives. Le ratio entre le délai d’expiration et l’intervalle de temps entre les évaluations doit être inférieur ou égal à 10.

En savoir plus sur le lancement de la mise en conformité des vérifications.

Vérifications multiples

Avant qu’Azure Pipelines déploie une phase dans une exécution de pipeline, plusieurs vérifications peuvent devoir être effectuées. Une ressource protégée peut avoir une ou plusieurs vérifications associées. Une phase peut utiliser plusieurs ressources protégées. Azure Pipelines collecte toutes les vérifications associées à chaque ressource protégée utilisée dans une phase et les évalue simultanément.

Une exécution de pipeline n’est autorisée à être déployée dans une phase que lorsque toutes les vérifications sont effectuées en même temps. Une seule décision finale négative entraîne le refus de l’accès au pipeline et l’échec de la phase.

Lorsque vous utilisez les vérifications de la manière recommandée (asynchrone, avec les états finaux), cela rend leurs décisions d’accès définitives et facilite la compréhension de l’état du système.

Consultez la section Approbations et vérifications multiples pour obtenir des exemples.

En savoir plus