Déclencheurs HTTP dans l’agent Azure SRE

Les déclencheurs HTTP dans Azure SRE Agent sont des points de terminaison webhook que les systèmes externes utilisent pour appeler votre agent à la demande. Lorsqu’un pipeline d’intégration continue et de livraison continue (CI/CD) échoue, un outil d’alerte détecte une anomalie ou tout client HTTP envoie une POST requête, l’agent reçoit le contexte de l’événement et commence à fonctionner immédiatement.

Le problème : les alertes et les échecs de pipeline ont besoin d’un tri manuel

Votre équipe dispose déjà d’outils d’alerte, d’observabilité et de flux de travail tels que Datadog, Dynatrace, Jira, Splunk et Grafana, ainsi que de pipelines CI/CD qui échouent. Quand un problème se produit, la réponse est la même chaque fois :

  • Un ingénieur reçoit une alerte : L’ingénieur ouvre l’outil de supervision, lit l’alerte, puis ouvre manuellement les journaux, les indicateurs et l’historique de déploiement dans plusieurs tableaux de bord pour déterminer ce qui s’est passé.
  • Un pipeline échoue : Quelqu’un doit arrêter ce qu’il ou elle fait, vérifier le résultat de la compilation, mettre en corrélation avec les modifications récentes et décider s’il faut revenir en arrière ou avancer avec une correction.
  • Le contexte est dispersé : L’alerte Datadog indique « pic d'utilisation du processeur sur prod-api ». La cause racine nécessite de corréler les journaux de trois services, de vérifier les déploiements récents et d’examiner les traces Dynatrace.

Fonctionnement des déclencheurs HTTP

Les déclencheurs HTTP vous permettent de connecter n’importe quel outil qui prend en charge les webhooks directement à votre instance de l’agent SRE. Au lieu d’un ingénieur effectuant un tri manuel, le système qui a détecté le problème, qu’il s’agisse d’une alerte Datadog, d’une anomalie Dynatrace, d’une transition de flux de travail Jira ou d’une défaillance de pipeline, indique à l’agent d’examiner. Le contexte est transmis automatiquement.

Chaque déclencheur est un point de terminaison webhook nommé sur votre agent avec une URL unique. Lorsqu’un système externe appelle cette URL via HTTP POST, l’agent exécute l’invite configurée du déclencheur, qui est enrichie avec toutes les données JSON dans le corps de la requête.

Concepts clés

Concept Fonctionnement
Déclencheur Un point de terminaison nommé avec un prompt, un agent affecté (par défaut ou sous-agent) et un niveau d’autonomie (autonome ou avec révision).
URL du déclencheur URL unique de webhook générée lors de la création d'un déclencheur. Cette URL de webhook est celle appelée par les outils externes.
Contexte JSON Corps JSON facultatif envoyé avec la POST requête. Cela devient une partie de la requête de l’agent afin qu’il dispose de tout le contexte.
Historique d’exécution Chaque appel est enregistré avec un horodatage, un lien de thread et un état de réussite ou d’échec.
Activer/désactiver Activer ou désactiver les déclencheurs sans suppression. Les déclencheurs désactivés retournent 404.

Appeler un déclencheur

Appelez l’URL du déclencheur avec une requête HTTP POST :

curl -X POST \
  https://your-agent.sre.azure.com/api/v1/httptriggers/trigger/<TRIGGER_ID> \
  -H "Authorization: Bearer <ARM_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "datadog",
    "alert_title": "High error rate on checkout-api",
    "severity": "critical",
    "service": "checkout-api",
    "region": "eastus2",
    "metric": "error_rate",
    "value": "8.2%",
    "threshold": "5%"
  }'
Élément Présentation
URL Point de terminaison unique du webhook du déclencheur. Recherchez-le dans l’affichage des détails du déclencheur sous l’URL du déclencheur.
Authorization Un jeton Bearer Azure Resource Manager. Consultez Authentification pour l’appel de déclencheur.
Type de contenu Doit être application/json si vous envoyez un corps JSON.
Corps du contenu JSON (facultatif) Toutes les données JSON que vous souhaitez voir pour l’agent. Ces données font partie de l’invite de l’agent. Incluez le contexte qui aide l’agent à examiner, comme le nom d’alerte, la gravité et le service affecté.

Le corps JSON est facultatif. Si vous appelez le déclencheur sans contenu, l’agent fonctionne uniquement avec l’invite configurée du déclencheur. Avec un corps de requête, l’agent voit à la fois la requête et les données que vous avez envoyées.

Authentification pour l’appel de déclencheur

Le point de terminaison du déclencheur nécessite un jeton Bearer Azure Resource Manager dans l’en-tête Authorization: Bearer <TOKEN>. L’appelant a besoin Microsoft.App/agents/threads/write d’une autorisation sur la ressource de l’agent.

Méthodes d’obtention d’un jeton

Méthode Idéal pour Détails
Principal du service Chaînes CI/CD, systèmes automatisés Créez un enregistrement d’application, attribuez le rôle sur la ressource de l’agent et utilisez le flux d’informations d’identification du client pour obtenir un jeton.
Identité managée Services hébergés par Azure (Azure Functions, machines virtuelles Azure, Azure Container Apps) Aucun secret à gérer. La ressource Azure s’authentifie automatiquement.
Azure CLI Test et développement Exécutez az account get-access-token --resource https://management.azure.com --query accessToken -o tsv.

Connecter des outils externes qui ne prennent pas en charge l’authentification Azure

Les outils tels que Datadog, Dynatrace, Jira et Splunk envoient des webhooks avec leurs propres formats d’authentification, et non des jetons Azure Resource Manager. Pour combler l’écart, utilisez l’un des intermédiaires suivants.

Intermédiaire Fonctionnement
Azure Functions Reçoit le webhook, acquiert un jeton Azure Resource Manager à l’aide de son identité managée et transfère l’appel à l’URL du déclencheur.
Azure Logic Apps Flux de travail sans code qui reçoit des webhooks provenant de n’importe quelle source et appelle des API Azure avec l’authentification Azure Resource Manager intégrée.
Gestion des API Azure Se trouve devant l’URL du déclencheur et gère la validation et la transformation du jeton via des stratégies.

Response

{
  "message": "HTTP trigger execution initiated",
  "executionTime": "2026-03-13T10:30:00Z",
  "threadId": "thread-abc123",
  "success": true
}

Le déclencheur retourne immédiatement HTTP 202 (accepté). L’agent traite la requête de façon asynchrone.

Ce qui rend cette approche différente

Les déclencheurs HTTP connectent vos outils d’alerte et CI/CD existants directement à votre agent sans ingénieur dans la boucle. Le système qui a détecté le problème informe l’agent d'enquêter et transmet automatiquement le contexte complet. Il n’existe aucune pagination, aucun changement de tableau de bord et aucune collecte manuelle de contexte.

Avant et après

Avant (triage manuel) Après (déclencheurs HTTP)
L’alerte Datadog se déclenche. L’ingénieur reçoit une alerte, ouvre trois tableaux de bord et commence à enquêter. Déclencheur d’appels webhook Datadog. L’agent examine et publie automatiquement les résultats.
Interruptions de pipeline. L’ingénieur vérifie les journaux de build, examine les PR (pull requests) et décide de la prochaine étape. Le gestionnaire d’échec du pipeline appelle le déclencheur. L’agent analyse l’échec et publie la cause racine.
Dynatrace détecte l’anomalie. L’ingénieur met en corrélation manuellement les services. Le webhook Dynatrace appelle le déclencheur avec le contexte de l’anomalie. L’agent met en corrélation les journaux de logs, les indicateurs et les déploiements.

Tâches planifiées et déclencheurs HTTP

Tâches planifiées Déclencheurs HTTP
Basé sur le temps (planification chronologique). Fondé sur les événements (sur demande).
Fonctionne indépendamment de l’occurrence d’un événement. S’exécute uniquement lorsqu’il est appelé.
Aucune entrée externe par exécution. Données de charge utile injectées dans chaque invocation.
Idéal pour les vérifications périodiques. Mieux pour les réactions pilotées par les événements.

Utilisez les deux ensemble. Utilisez des tâches planifiées pour la surveillance proactive et les déclencheurs HTTP pour la gestion des événements réactifs.

Cas d’utilisation

Intégration de pipeline CI/CD

Lorsqu’un pipeline de déploiement échoue, appelez l’agent pour analyser l’échec :

# In your pipeline's failure handler
curl -X POST "$AGENT_TRIGGER_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"pipeline\": \"$PIPELINE_NAME\", \"run_id\": \"$RUN_ID\", \"error\": \"$ERROR_MESSAGE\"}"

Investigation pilotée par les alertes

Connectez votre système d’alerte pour déclencher une investigation automatisée lorsque des alertes critiques se déclenchent :

{
  "alert_name": "Error rate > 5%",
  "severity": "P1",
  "service": "checkout-api",
  "region": "eastus2",
  "start_time": "2026-03-13T10:15:00Z"
}

Vérifications de conformité du déploiement

Une fois le déploiement terminé, déclenchez une révision de conformité :

curl -X POST "$AGENT_TRIGGER_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -d '{"deployment_id": "deploy-456", "environment": "production", "changes": ["config update", "image bump"]}'

Référence d’API

Point de terminaison Méthode Description
/api/v1/httptriggers GET Répertorier tous les déclencheurs.
/api/v1/httptriggers/create POST Créez un nouveau déclencheur.
/api/v1/httptriggers/{id} GET Obtenir les détails du déclencheur.
/api/v1/httptriggers/{id} PUT Mettez à jour les propriétés du déclencheur.
/api/v1/httptriggers/{id} DELETE Supprimez un déclencheur.
/api/v1/httptriggers/{id}/enable POST Activez un déclencheur.
/api/v1/httptriggers/{id}/disable POST Désactivez un déclencheur.
/api/v1/httptriggers/{id}/execute POST Exécutez un déclencheur manuellement.
/api/v1/httptriggers/{id}/executions GET Obtenir l’historique d’exécution.
/api/v1/httptriggers/trigger/{id} POST Point de terminaison webhook externe.

Résolution des problèmes

Le déclencheur renvoie une erreur 404

  • Vérifiez que le déclencheur est activé. Les déclencheurs désactivés retournent 404.
  • Vérifiez que l’ID de déclencheur dans l’URL est correct.

401 Non autorisé

  • L’audience du jeton doit correspondre à l’ID d’application d’Agent SRE, pas à https://management.azure.com.
  • Pour obtenir un jeton à des fins de test, utilisez az account get-access-token --resource 59f0a04a-b322-4310-adc9-39ac41e9631e --query accessToken -o tsv.

Le déclencheur s’exécute, mais l’agent n’agit pas

  • Vérifiez l’invite de l’agent. Une invite vide peut ne pas produire de sortie utile.
  • Vérifiez que le sous-agent choisi dispose des outils nécessaires à la tâche.
  • Vérifiez l’historique d’exécution pour obtenir les détails de l’erreur.

Limites

Ressource Limite
Déclencheurs par agent Pas de limite difficile.
Nombre maximal de tours par exécution 250 tours.
Authentication Un jeton Bearer est requis pour chaque URL de déclencheur.

Contenu connexe

  • Last updated on