Démarrer un runbook depuis un webhook

Article
12/21/2023

Un webhook permet à un service externe de démarrer un runbook particulier dans Azure Automation via une simple requête HTTP. Ces services externes incluent Azure DevOps Services, GitHub, les journaux Azure Monitor et les applications personnalisées. De tels services peuvent utiliser un Webhook pour démarrer un runbook sans implémenter toute l’API Azure Automation. Pour comparer les webhooks aux autres méthodes de démarrage d’un runbook, consultez Démarrage d’un runbook dans Azure Automation.

Présentation des webhooks

Pour comprendre les exigences client pour le protocole TLS 1.2 ou version ultérieure avec des webhooks, consultez TLS pour Azure Automation.

Propriétés des webhooks

Le tableau suivant décrit les propriétés que vous devez configurer pour un webhook.

Propriété	Description
Nom	Nom du webhook. Vous pouvez attribuer le nom de votre choix, puisque celui-ci n’est pas visible par le client. Il sert seulement à identifier le runbook dans Azure Automation. À titre de meilleure pratique, nommez le webhook d’après le client qui l’utilise.
URL	URL du webhook. Il s’agit de l’adresse unique qu’un client appelle avec une méthode HTTP POST pour démarrer le runbook lié au webhook. Elle est générée automatiquement lorsque vous créez le webhook. Vous ne pouvez pas spécifier d’URL personnalisée. L’URL contient un jeton de sécurité qui permet à un système tiers d’appeler le runbook sans authentification supplémentaire. Pour cette raison, vous devez traiter l’URL comme un mot de passe. Pour des raisons de sécurité, vous pouvez uniquement afficher l’URL dans le portail Azure au moment de la création du webhook. Notez l'URL dans un emplacement sécurisé en vue d'une utilisation ultérieure.
Date d'expiration	Date d’expiration du webhook, après laquelle il ne peut plus être utilisé. Vous pouvez modifier la date d’expiration du webhook après sa création, tant que celui-ci n’a pas expiré.
Enabled	Paramètre indiquant si le webhook doit être activé par défaut lors de sa création. Si vous affectez la valeur Disabled à cette propriété, aucun client ne pourra utiliser le webhook. Vous pouvez définir cette propriété pendant ou après la création du webhook.

Paramètres utilisés lorsque le webhook démarre un runbook

Un webhook peut définir les valeurs des paramètres du runbook qui sont utilisées au démarrage de celui-ci. Le webhook doit inclure les valeurs de tous les paramètres obligatoires du runbook, et peut inclure les valeurs des paramètres facultatifs. Une valeur de paramètre configurée pour un webhook peut être modifiée même après la création de celui-ci. Plusieurs webhooks liés à un même runbook peuvent utiliser des valeurs différentes pour les paramètres du runbook. Lorsqu’un client démarre un runbook à l’aide d’un webhook, il ne peut pas remplacer les valeurs de paramètres définies dans le webhook.

Pour recevoir des données du client, le runbook accepte un paramètre unique appelé WebhookData. Ce paramètre définit un objet contenant les données que le client inclut dans une requête POST.

Propriétés WebhookData

Le paramètre WebhookData possède les propriétés suivantes :

Propriété	Description
WebhookName	Nom du webhook.
RequestHeader	PSCustomObject contenant les en-têtes de la requête POST entrante.
RequestBody	Corps de la requête POST entrante. Le corps conserve la mise en forme des données (chaînes, JSON, XML ou données encodées dans un formulaire). Le Runbook doit être écrit pour fonctionner avec le format de données qui est attendu.

Aucune configuration du webhook n’est nécessaire pour prendre en charge le paramètre WebhookData. En outre, le runbook n’est pas obligé de l’accepter. Si le runbook ne définit pas le paramètre, tous les détails de la requête envoyée à partir du client sont ignorés.

Remarque

Lors de l’appel d’un webhook, le client doit toujours stocker toutes les valeurs de paramètre en cas d’échec de l’appel. En cas de panne réseau ou de problème de connexion, l’application ne pourra pas récupérer les appels de webhook qui ont échoué.

Si vous spécifiez une valeur pour WebhookData lors de la création du webhook, celle-ci est remplacée quand le webhook démarre le runbook avec les données de la demande POST du client. Cela se produit même si l’application n’inclut aucune donnée dans le corps de la demande.

Si vous démarrez un runbook qui définit WebhookData à l’aide d’un mécanisme autre qu’un webhook, vous pouvez fournir une valeur pour WebhookData que le runbook reconnaîtra. Cette valeur doit correspondre à un objet ayant les mêmes propriétés que le paramètre WebhookData, afin que le runbook puisse l’utiliser de la même manière qu’il utilise les objets WebhookData qui sont passés par un webhook.

Par exemple, si vous démarrez le runbook suivant à partir du portail Azure et souhaitez passer des exemples de données de webhook à des fins de test, vous devez passer ces données au format JSON dans l’interface utilisateur.

Paramètre WebhookData à partir de l'interface utilisateur

Dans l’exemple de runbook suivant, nous allons définir les propriétés suivantes pour WebhookData :

WebhookName : MyWebhook
RequestBody : *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*

Nous passons maintenant l’objet JSON suivant dans l’interface utilisateur pour le paramètre WebhookData. Cet exemple, avec les retours chariot et les caractères de nouvelle ligne, correspond au format qui est passé à partir d’un webhook.

{"WebhookName":"mywebhook","RequestBody":"[\r\n {\r\n \"ResourceGroup\": \"vm01\",\r\n \"Name\": \"vm01\"\r\n },\r\n {\r\n \"ResourceGroup\": \"vm02\",\r\n \"Name\": \"vm02\"\r\n }\r\n]"}

Démarrage du paramètre WebhookData à partir de l'interface utilisateur

Remarque

Azure Automation journalise les valeurs de tous les paramètres d’entrée associés au travail de runbook. Par conséquent, toutes les entrées fournies par le client dans la requête webhook seront journalisées et accessibles à toute personne ayant accès au travail Automation. Pour cette raison, soyez prudent lorsque vous incluez des informations sensibles dans les appels du webhook.

Sécurité des webhooks

La sécurité d’un webhook dépend de la confidentialité de son URL, laquelle contient un jeton de sécurité permettant au webhook d’être appelé. Azure Automation n’effectue pas d’authentification de la demande tant que celle-ci est adressée à l’URL appropriée. Par conséquent, vos clients ne doivent pas utiliser les webhooks pour les runbooks qui exécutent des opérations hautement sensibles, sans recourir à un autre moyen de validation de la demande.

Réfléchissez aux stratégies suivantes :

Vous pouvez inclure une logique dans un runbook pour déterminer si celui-ci est appelé par un webhook. Indiquez au runbook de vérifier la propriété WebhookName du paramètre WebhookData. Le runbook peut effectuer une validation supplémentaire en recherchant des informations spécifiques dans les propriétés RequestHeader et RequestBody.
Faites en sorte que le runbook valide une condition externe quand il reçoit une demande de webhook. Par exemple, imaginez un runbook qui soit appelé par GitHub à chaque nouvelle validation effectuée dans un dépôt GitHub. Avant de poursuivre, le runbook peut se connecter à GitHub pour vérifier qu’une nouvelle validation s’est produite.
Azure Automation prend en charge les étiquettes de service de réseau virtuel Azure, plus précisément GuestAndHybridManagement. Vous pouvez utiliser des étiquettes de service pour définir des contrôles d’accès réseau sur des groupes de sécurité réseau ou sur le pare-feu Azure et déclencher des webhooks à partir de votre réseau virtuel. Les étiquettes de service peuvent être utilisées à la place d’adresses IP spécifiques pendant la création de règles de sécurité. En spécifiant le nom d’étiquette de service GuestAndHybridManagement dans le champ source ou de destination approprié d’une règle, vous pouvez autoriser ou refuser le trafic pour le service Automation. Cette étiquette de service ne permet pas d’autoriser un contrôle plus précis en limitant les plages d’adresses IP à une région spécifique.

Créer un webhook

Remarque

Lorsque vous utilisez le webhook avec un runbook PowerShell 7, il convertit automatiquement le paramètre d’entrée du webhook en JSON non valide. Pour plus d’informations, consultez Problèmes connus – PowerShell 7.1 (préversion). Nous vous recommandons d’utiliser le webhook avec le runbook PowerShell 5.

Créez un runbook PowerShell à l’aide du code suivant :

param
(
    [Parameter(Mandatory=$false)]
    [object] $WebhookData
)

write-output "start"
write-output ("object type: {0}" -f $WebhookData.gettype())
write-output $WebhookData
write-output "`n`n"
write-output $WebhookData.WebhookName
write-output $WebhookData.RequestBody
write-output $WebhookData.RequestHeader
write-output "end"

if ($WebhookData.RequestBody) { 
    $names = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

        foreach ($x in $names)
        {
            $name = $x.Name
            Write-Output "Hello $name"
        }
}
else {
    Write-Output "Hello World!"
}

Créez un webhook à l’aide du portail Azure, PowerShell ou l’API REST. Un webhook a besoin d’un runbook publié. Cette procédure pas à pas utilise une version modifiée du runbook créé dans Créer un runbook Azure Automation.
1. Connectez-vous au portail Azure.
2. Sur le Portail Azure, accédez à votre compte Automation.
3. Sous Automation du processus, cliquez sur Runbooks pour ouvrir la page Runbooks.
4. Sélectionnez votre runbook dans la liste pour ouvrir la page Vue d’ensemble du runbook.
5. Sélectionnez Ajouter un webhook pour ouvrir la page Ajouter un webhook.
6. Dans la page Ajouter un webhook, sélectionnez Créer un webhook.
7. Entrez le nom du webhook. La date d’expiration par défaut pour le champ Expire est d’un an à partir de la date actuelle.
8. Cliquez sur l’icône de copie ou appuyez sur Ctrl + C pour copier l’URL du webhook. Ensuite, enregistrez l’URL en lieu sûr.
  
  Important
  
  Une fois que vous avez créé le webhook,vous ne pouvez plus récupérer l’URL. Veillez à le copier et à l’enregistrer comme ci-dessus.
9. Sélectionnez OK pour revenir à la page Ajouter un webhook.
10. Dans la page Ajouter un webhook, sélectionnez Configurer les paramètres et les paramètres d’exécution pour ouvrir la page Paramètres.
11. Passez en revue la page Paramètres. Pour l’exemple de runbook utilisé dans cet article, aucune modification n’est nécessaire. Sélectionnez OK pour revenir à la page Ajouter un webhook.
12. Dans la page Ajouter un webhook, sélectionnez Créer. Le webhook est créé et vous êtes redirigé vers la page Vue d’ensemble du runbook.
1. Vérifiez que vous avez la dernière version du module Az de PowerShell.
2. Connectez-vous à Azure de manière interactive à l’aide de la cmdlet Connect-AzAccount et suivez les instructions.
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
3. Utilisez l’applet de commande New-AzAutomationWebhook pour créer un webhook pour un runbook Automation. Fournissez une valeur appropriée pour les variables, puis exécutez le script.
```
# Initialize variables with your relevant values
$resourceGroup = "resourceGroupName"
$automationAccount = "automationAccountName"
$runbook = "runbookName"
$psWebhook = "webhookName"

# Create webhook
$newWebhook = New-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook `
    -RunbookName $runbook `
    -IsEnabled $True `
    -ExpiryTime "12/31/2022" `
    -Force

# Store URL in variable; reveal variable
$uri = $newWebhook.WebhookURI
$uri
```
  La sortie est une URL qui ressemble à : https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
4. Vous pouvez également vérifier le webhook avec l’applet de commande PowerShell Get-AzAutomationWebhook.
```
Get-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook
```
La commande PUT est documentée dans Webhook - Create ou Update. Cet exemple utilise l’applet de commande PowerShell Invoke-RestMethod pour envoyer la demande PUT.
1. Créez un fichier appelé webhook.json et collez-y le code suivant :
```
{
"name": "RestWebhook",
"properties": {
    "isEnabled": true,
    "expiryTime": "2022-03-29T22:18:13.7002872Z",
    "runbook": {
    "name": "runbookName"
    }
}
}
```
  Avant d’exécuter, modifiez la valeur de la propriété runbook:name en spécifiant le vrai nom de votre runbook. Passez en revue Propriétés des webhooks pour plus d’informations sur ces propriétés.
2. Vérifiez que vous avez la dernière version du module Az de PowerShell.
3. Connectez-vous à Azure de manière interactive à l’aide de la cmdlet Connect-AzAccount et suivez les instructions.
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
4. Fournissez une valeur appropriée pour les variables, puis exécutez le script.
```
# Initialize variables
$subscription = "subscriptionID"
$resourceGroup = "resourceGroup"
$automationAccount = "automationAccount"
$runbook = "runbookName"
$restWebhook = "webhookName"
$file = "path\webhook.json"

# consume file
$body = Get-Content $file

# Craft Uri
$restURI = "https://management.azure.com/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.Automation/automationAccounts/$automationAccount/webhooks/$restWebhook`?api-version=2015-10-31"
```
5. Exécutez le script suivant pour obtenir un jeton d’accès. Si votre jeton d’accès a expiré, vous devez réexécuter le script.
```
# Obtain access token
$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}
```
6. Exécutez le script suivant pour créer le webhook à l’aide de l’API REST.
```
# Invoke the REST API
# Store URL in variable; reveal variable
$response = Invoke-RestMethod -Uri $restURI -Method Put -Headers $authHeader -Body $body
$webhookURI = $response.properties.uri
$webhookURI
```
  La sortie est une URL qui ressemble à : https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
7. Vous pouvez également utiliser Webhook - Get pour récupérer le webhook identifié par son nom. Vous pouvez exécuter les commandes PowerShell suivantes :
```
$response = Invoke-RestMethod -Uri $restURI -Method GET -Headers $authHeader
$response | ConvertTo-Json
```

Utiliser un webhook

Cet exemple utilise l’applet de commande PowerShell Invoke-WebRequest pour envoyer la demande POST à votre nouveau webhook.

Préparez les valeurs à passer au runbook en tant que corps de l’appel de webhook. Pour des valeurs relativement simples, vous pouvez écrire le script des valeurs comme suit :
```
$Names  = @(
            @{ Name="Hawaii"},
            @{ Name="Seattle"},
            @{ Name="Florida"}
        )

$body = ConvertTo-Json -InputObject $Names
```
Pour de plus grandes séries de valeurs, vous pouvez utiliser un fichier. Créez un fichier nommé names.json et collez-y le code suivant :
```
[
    { "Name": "Hawaii" },
    { "Name": "Florida" },
    { "Name": "Seattle" }
]
```
Remplacez la valeur de la variable $file par le vrai chemin du fichier JSON avant d’exécuter les commandes PowerShell suivantes.
```
# Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file 
```

Exécutez les commandes PowerShell suivantes pour appeler le webhook à l’aide de l’API REST.

$response = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $body -UseBasicParsing
$response

$responseFile = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $bodyFile -UseBasicParsing
$responseFile

À des fins d’illustration, deux appels ont été effectués pour les deux méthodes différentes de production du corps. Pour la production, utilisez une seule méthode. La sortie doit ressembler à ce qui suit (une seule sortie est affichée) :

Sortie de l’appel de webhook

Le client reçoit de la requête POST l’un des codes de retour suivants.

Code	Texte	Description
202	Acceptée	La requête a été acceptée et le Runbook a été mis en file d'attente avec succès.
400	Demande incorrecte	La demande n’a pas été acceptée pour l’une des raisons suivantes : Le webhook a expiré. Le webhook est désactivé. Le jeton de l’URL n’est pas valide.
404	Introuvable	La demande n’a pas été acceptée pour l’une des raisons suivantes : Le webhook est introuvable. Le runbook est introuvable. Le compte est introuvable.
500	Erreur interne du serveur	L'URL est valide, mais une erreur s'est produite. Soumettez à nouveau la demande.

Si la requête aboutit, la réponse webhook contiendra l’ID de travail au format JSON, comme illustré ci-dessous. Elle contiendra un seul ID de travail. Toutefois, le format JSON permettra des améliorations ultérieures potentielles.

{"JobIds":["<JobId>"]}

L’applet de commande PowerShell Get-AzAutomationJobOutput sera utilisée pour récupérer la sortie. L’API Azure Automation peut également être utilisée.
```
#isolate job ID
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

# Get output
Get-AzAutomationJobOutput `
    -AutomationAccountName $automationAccount `
    -Id $jobid `
    -ResourceGroupName $resourceGroup `
    -Stream Output
```
Quand vous déclenchez un runbook créé à l’étape précédente, un travail est créé et la sortie doit ressembler à ce qui suit :

Mettre à jour un webhook

Lorsqu’un webhook est créé, il reste valide pendant 10 ans, puis expire automatiquement. Une fois que le webhook a expiré, vous ne pouvez pas le réactiver. Vous pouvez uniquement le supprimer, puis le recréer. Vous pouvez prolonger la durée de validité d’un webhook qui n’a pas encore expiré. Pour étendre un webhook, effectuez les étapes suivantes.

Accédez au runbook qui contient le webhook.
Sous Ressources, sélectionnez Webhooks, puis le webhook que vous voulez étendre.
Dans la page Webhook, choisissez une nouvelle date et une nouvelle heure d’expiration, puis sélectionnez Enregistrer.

Passez en revue l’appel d’API Webhook - Update et l’applet de commande PowerShell Set-AzAutomationWebhook pour d’autres modifications possibles.

Nettoyer les ressources

Voici des exemples de suppression d’un webhook d’un runbook Automation.

Avec PowerShell, vous pouvez utiliser l’applet de commande Remove-AzAutomationWebhook comme indiqué ci-dessous. Aucune sortie n’est retournée.
```
Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook
```
Avec REST, vous pouvez utiliser l’API REST Webhook - Delete comme indiqué ci-dessous.
```
Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader
```
Une sortie de StatusCode : 200 signifie que la suppression a réussi.

Créer un runbook et un webhook avec un modèle ARM

Il est également possible de créer des webhooks Automation à l’aide des modèles Azure Resource Manager. Cet exemple de modèle crée un compte Automation, quatre runbooks et un webhook pour le runbook nommé.

Créez un fichier nommé webhook_deploy.json et collez-y le code suivant :

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "automationAccountName": {
            "type": "String",
            "metadata": {
                "description": "Automation account name"
            }
        },
        "webhookName": {
            "type": "String",
            "metadata": {
                "description": "Webhook Name"
            }
        },
        "runbookName": {
            "type": "String",
            "metadata": {
                "description": "Runbook Name for which webhook will be created"
            }
        },
        "WebhookExpiryTime": {
            "type": "String",
            "metadata": {
                "description": "Webhook Expiry time"
            }
        },
        "_artifactsLocation": {
            "defaultValue": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.automation/101-automation/",
            "type": "String",
            "metadata": {
                "description": "URI to artifacts location"
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Automation/automationAccounts",
            "apiVersion": "2020-01-13-preview",
            "name": "[parameters('automationAccountName')]",
            "location": "[resourceGroup().location]",
            "properties": {
                "sku": {
                    "name": "Free"
                }
            },
            "resources": [
                {
                    "type": "runbooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('runbookName')]",
                    "location": "[resourceGroup().location]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]"
                    ],
                    "properties": {
                        "runbookType": "Python2",
                        "logProgress": "false",
                        "logVerbose": "false",
                        "description": "Sample Runbook",
                        "publishContentLink": {
                            "uri": "[uri(parameters('_artifactsLocation'), 'scripts/AzureAutomationTutorialPython2.py')]",
                            "version": "1.0.0.0"
                        }
                    }
                },
                {
                    "type": "webhooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('webhookName')]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]",
                        "[parameters('runbookName')]"
                    ],
                    "properties": {
                        "isEnabled": true,
                        "expiryTime": "[parameters('WebhookExpiryTime')]",
                        "runbook": {
                            "name": "[parameters('runbookName')]"
                        }
                    }
                }
            ]
        }
    ],
    "outputs": {
        "webhookUri": {
            "type": "String",
            "value": "[reference(parameters('webhookName')).uri]"
        }
    }
}

L’exemple de code PowerShell suivant déploie le modèle à partir de votre machine. Fournissez une valeur appropriée pour les variables, puis exécutez le script.

$resourceGroup = "resourceGroup"
$templateFile = "path\webhook_deploy.json"
$armAutomationAccount = "automationAccount"
$armRunbook = "ARMrunbookName"
$armWebhook = "webhookName"
$webhookExpiryTime = "12-31-2022"

New-AzResourceGroupDeployment `
    -Name "testDeployment" `
    -ResourceGroupName $resourceGroup `
    -TemplateFile $templateFile `
    -automationAccountName $armAutomationAccount `
    -runbookName $armRunbook `
    -webhookName $armWebhook `
    -WebhookExpiryTime $webhookExpiryTime

Remarque

Pour des raisons de sécurité, l’URI n’est retourné que la première fois qu’un modèle est déployé.

Étapes suivantes

Pour déclencher un runbook à partir d’une alerte, consultez Utiliser une alerte pour déclencher un runbook Azure Automation.

Démarrer un runbook depuis un webhook

Propriétés des webhooks

Paramètres utilisés lorsque le webhook démarre un runbook

Sécurité des webhooks

Créer un webhook

Utiliser un webhook

Mettre à jour un webhook

Nettoyer les ressources

Créer un runbook et un webhook avec un modèle ARM

Étapes suivantes

Ressources supplémentaires