Démarrer un runbook depuis un WebhookStart a runbook from a webhook

Un webhook permet à un service externe de démarrer un runbook particulier dans Azure Automation via une simple requête HTTP.A webhook allows an external service to start a particular runbook in Azure Automation through a single HTTP request. Ces services externes incluent Azure DevOps Services, GitHub, les journaux Azure Monitor et les applications personnalisées.External services include Azure DevOps Services, GitHub, Azure Monitor logs, and custom applications. De tels services peuvent utiliser un Webhook pour démarrer un runbook sans implémenter toute l’API Azure Automation.Such a service can use a webhook to start a runbook without implementing the full Azure Automation API. Pour comparer les webhooks aux autres méthodes de démarrage d’un runbook, consultez Démarrage d’un runbook dans Azure Automation.You can compare webhooks to other methods of starting a runbook in Starting a runbook in Azure Automation.

Nota

L’utilisation d’un webhook pour démarrer un runbook Python n’est pas prise en charge.Using a webhook to start a Python runbook is not supported.

Présentation des webhooks

Pour comprendre la configuration requise du client pour le protocole TLS 1.2 avec les webhooks, consultez Application de TLS 1.2 pour Azure Automation.To understand client requirements for TLS 1.2 with webhooks, see TLS 1.2 enforcement for Azure Automation.

Propriétés des webhooksWebhook properties

Le tableau suivant décrit les propriétés que vous devez configurer pour un webhook.The following table describes the properties that you must configure for a webhook.

PropriétéProperty DescriptionDescription
NomName Nom du webhook.Name of the webhook. Vous pouvez attribuer le nom de votre choix, puisque celui-ci n’est pas visible par le client.You can provide any name you want, since it isn't exposed to the client. Il sert seulement à identifier le runbook dans Azure Automation.It's only used for you to identify the runbook in Azure Automation. À titre de meilleure pratique, nommez le webhook d’après le client qui l’utilise.As a best practice, you should give the webhook a name related to the client that uses it.
URLURL URL du webhook.URL of the 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.This is the unique address that a client calls with an HTTP POST to start the runbook linked to the webhook. Elle est générée automatiquement lorsque vous créez le webhook.It's automatically generated when you create the webhook. Vous ne pouvez pas spécifier d’URL personnalisée.You can't specify a custom URL.

L’URL contient un jeton de sécurité qui permet à un système tiers d’appeler le runbook sans authentification supplémentaire.The URL contains a security token that allows a third-party system to invoke the runbook with no further authentication. Pour cette raison, vous devez traiter l’URL comme un mot de passe.For this reason, you should treat the URL like a password. Pour des raisons de sécurité, vous pouvez uniquement afficher l’URL dans le portail Azure au moment de la création du webhook.For security reasons, you can only view the URL in the Azure portal when creating the webhook. Notez l'URL dans un emplacement sécurisé en vue d'une utilisation ultérieure.Note the URL in a secure location for future use.
Date d'expirationExpiration date Date d’expiration du webhook, après laquelle il ne peut plus être utilisé.Expiration date of the webhook, after which it can no longer be used. Vous pouvez modifier la date d’expiration du webhook après sa création, tant que celui-ci n’a pas encore expiré.You can modify the expiration date after the webhook is created, as long as the webhook has not expired.
activéEnabled Paramètre indiquant si le webhook doit être activé par défaut lors de sa création.Setting indicating if the webhook is enabled by default when it's created. Si vous affectez la valeur Disabled à cette propriété, aucun client ne pourra utiliser le webhook.If you set this property to Disabled, no client can use the webhook. Vous pouvez définir cette propriété pendant ou après la création du webhook.You can set this property when you create the webhook or any other time after its creation.

Paramètres utilisés lorsque le webhook démarre un runbookParameters used when the webhook starts a runbook

Un webhook peut définir les valeurs des paramètres du runbook qui sont utilisées au démarrage de celui-ci.A webhook can define values for runbook parameters that are used when the runbook starts. Le webhook doit inclure les valeurs de tous les paramètres obligatoires du runbook, et peut inclure les valeurs des paramètres facultatifs.The webhook must include values for any mandatory runbook parameters and can include values for optional parameters. Une valeur de paramètre configurée pour un webhook peut être modifiée même après la création de celui-ci.A parameter value configured to a webhook can be modified even after webhook creation. Plusieurs webhooks liés à un même runbook peuvent utiliser des valeurs différentes pour les paramètres du runbook.Multiple webhooks linked to a single runbook can each use different runbook parameter values. 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.When a client starts a runbook using a webhook, it can't override the parameter values defined in the webhook.

Pour recevoir des données du client, le runbook accepte un paramètre unique appelé WebhookData.To receive data from the client, the runbook supports a single parameter called WebhookData. Ce paramètre définit un objet contenant les données que le client inclut dans une requête POST.This parameter defines an object containing data that the client includes in a POST request.

Propriétés WebhookData

Le paramètre WebhookData possède les propriétés suivantes :The WebhookData parameter has the following properties:

PropriétéProperty DescriptionDescription
WebhookName Nom du webhook.Name of the webhook.
RequestHeader Table de hachage contenant les en-têtes de la requête POST entrante.Hashtable containing the headers of the incoming POST request.
RequestBody Corps de la requête POST entrante.Body of the incoming POST request. Le corps conserve les mises en forme de données (chaînes, JSON, XML ou données encodées dans un formulaire).This body retains any data formatting, such as string, JSON, XML, or form-encoded. Le Runbook doit être écrit pour fonctionner avec le format de données qui est attendu.The runbook must be written to work with the data format that is expected.

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.There's no configuration of the webhook required to support the WebhookData parameter, and the runbook isn't required to accept it. 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.If the runbook doesn't define the parameter, any details of the request sent from the client are ignored.

Nota

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.When calling a webhook, the client should always store any parameter values in case the call fails. 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é.If there is a network outage or connection issue, the application can't retrieve failed webhook calls.

Si vous spécifiez une valeur pour WebhookData lors de la création du webhook, celle-ci sera remplacée lorsque le webhook démarrera le runbook avec les données de la requête POST du client.If you specify a value for WebhookData at webhook creation, it is overridden when the webhook starts the runbook with the data from the client POST request. Cela se produit même s’il n’existe aucune donnée dans le corps de la requête de l’application.This happens even if the application does not include any data in the request body.

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.If you start a runbook that defines WebhookData using a mechanism other than a webhook, you can provide a value for WebhookData that the runbook recognizes. 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.This value should be an object with the same properties as the WebhookData parameter so that the runbook can work with it just as it works with actual WebhookData objects passed by a 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.For example, if you are starting the following runbook from the Azure portal and want to pass some sample webhook data for testing, you must pass the data in JSON in the user interface.

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 :For the next runbook example, let's define the following properties for WebhookData:

  • WebhookName : MyWebhookWebhookName: MyWebhook
  • RequestBody : *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*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.Now we pass the following JSON object in the UI for the WebhookData parameter. Cet exemple, avec les retours chariot et les caractères de nouvelle ligne, correspond au format qui est passé à partir d’un webhook.This example, with carriage returns and newline characters, matches the format that is passed in from a 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

Nota

Azure Automation journalise les valeurs de tous les paramètres d’entrée associés au travail de runbook.Azure Automation logs the values of all input parameters with the runbook job. 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.Thus any input provided by the client in the webhook request is logged and available to anyone with access to the automation job. Pour cette raison, soyez prudent lorsque vous incluez des informations sensibles dans les appels du webhook.For this reason, you should be cautious about including sensitive information in webhook calls.

Sécurité des webhooksWebhook security

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é.The security of a webhook relies on the privacy of its URL, which contains a security token that allows the webhook to be invoked. Azure Automation n’effectue pas d’authentification de la requête tant que celle-ci est adressée à la bonne URL.Azure Automation does not perform any authentication on a request as long as it is made to the correct URL. Pour cette raison, 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 requête.For this reason, your clients should not use webhooks for runbooks that perform highly sensitive operations without using an alternate means of validating the request.

Tenez compte des stratégies suivantes :Consider the following strategies:

  • Vous pouvez inclure une logique dans un runbook pour déterminer si celui-ci est appelé par un webhook.You can include logic within a runbook to determine if it is called by a webhook. Indiquez au runbook de vérifier la propriété WebhookName du paramètre WebhookData.Have the runbook check the WebhookName property of the WebhookData parameter. Le runbook peut effectuer une validation supplémentaire en recherchant des informations spécifiques dans les propriétés RequestHeader et RequestBody.The runbook can perform further validation by looking for particular information in the RequestHeader and RequestBody properties.

  • Faites en sorte que le runbook valide une condition externe quand il reçoit une demande de webhook.Have the runbook perform some validation of an external condition when it receives a webhook request. Par exemple, imaginez un runbook qui soit appelé par GitHub à chaque nouvelle validation effectuée dans un dépôt GitHub.For example, consider a runbook that is called by GitHub any time there's a new commit to a GitHub repository. Avant de poursuivre, le runbook peut se connecter à GitHub pour vérifier qu’une nouvelle validation s’est produite.The runbook might connect to GitHub to validate that a new commit has occurred before continuing.

  • Azure Automation prend en charge les étiquettes de service de réseau virtuel Azure, plus précisément GuestAndHybridManagement.Azure Automation supports Azure virtual network service tags, specifically 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.You can use service tags to define network access controls on network security groups or Azure Firewall and trigger webhooks from within your virtual network. 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é.Service tags can be used in place of specific IP addresses when you create security rules. 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.By specifying the service tag name GuestAndHybridManagement in the appropriate source or destination field of a rule, you can allow or deny the traffic for the Automation service. Cette étiquette de service ne permet pas d’autoriser un contrôle plus granulaire en limitant les plages d’adresses IP à une région spécifique.This service tag does not support allowing more granular control by restricting IP ranges to a specific region.

Créer un webhookCreate a webhook

Utilisez la procédure suivante pour créer un webhook lié à un Runbook dans le portail Azure.Use the following procedure to create a new webhook linked to a runbook in the Azure portal.

  1. Dans la page Runbooks du portail Azure, cliquez sur le runbook que le webhook démarre afin d’afficher les informations relatives au runbook.From the Runbooks page in the Azure portal, click the runbook that the webhook starts to view the runbook details. Vérifiez que le champ État du runbook est défini sur Publié.Ensure that the runbook Status field is set to Published.

  2. Cliquez sur Webhook en haut de la page pour ouvrir la page Ajouter un webhook.Click Webhook at the top of the page to open the Add Webhook page.

  3. Cliquez sur Créer un webhook pour ouvrir la page Créer un webhook.Click Create new webhook to open the Create Webhook page.

  4. Renseignez les champs Nom et Date d’expiration pour le webhook, et spécifiez si celui-ci doit être activé.Fill in the Name and Expiration Date fields for the webhook and specify if it should be enabled. Pour plus d’informations sur ces propriétés, consultez Propriétés des webhooks.See Webhook properties for more information about these properties.

  5. Cliquez sur l'icône de copie et appuyez sur Ctrl + C pour copier l'URL du webhook.Click the copy icon and press Ctrl+C to copy the URL of the webhook. Puis enregistrez-la dans un endroit sûr.Then record it in a safe place.

    Nota

    Une fois que vous avez créé le webhook,vous ne pouvez plus récupérer l’URL.Once you create the webhook, you cannot retrieve the URL again.

    URL du webhook

  6. Cliquez sur Paramètres pour fournir les valeurs des paramètres du Runbook.Click Parameters to provide values for the runbook parameters. Si le runbook a des paramètres obligatoires, vous ne pouvez pas créer le webhook sans fournir de valeurs.If the runbook has mandatory parameters, you can't create the webhook unless you provide values.

  7. Cliquez sur Créer pour créer le webhook.Click Create to create the webhook.

Utiliser un webhookUse a webhook

Pour utiliser un webhook après sa création, votre client doit émettre une requête HTTP POST avec l’URL du webhook.To use a webhook after it has been created, your client must issue an HTTP POST request with the URL for the webhook. La syntaxe est :The syntax is:

http://<Webhook Server>/token?=<Token Value>

Le client reçoit de la requête POST l’un des codes de retour suivants.The client receives one of the following return codes from the POST request.

CodeCode TexteText DescriptionDescription
202202 AcceptéeAccepted La requête a été acceptée et le Runbook a été mis en file d'attente avec succès.The request was accepted, and the runbook was successfully queued.
400400 Demande incorrecteBad Request La requête a été refusée pour l'une des raisons suivantes :The request was not accepted for one of the following reasons:
  • Le webhook a expiré.The webhook has expired.
  • Le webhook est désactivé.The webhook is disabled.
  • Le jeton de l’URL n’est pas valide.The token in the URL is invalid.
404404 IntrouvableNot Found La requête a été refusée pour l'une des raisons suivantes :The request was not accepted for one of the following reasons:
  • Le webhook est introuvable.The webhook was not found.
  • Le Runbook est introuvable.The runbook was not found.
  • Le compte est introuvable.The account was not found.
500500 Erreur interne du serveurInternal Server Error L'URL est valide, mais une erreur s'est produite.The URL was valid, but an error occurred. Soumettez à nouveau la demande.Please resubmit the request.

Si la requête aboutit, la réponse webhook contiendra l’ID de travail au format JSON, comme illustré ci-dessous.Assuming the request is successful, the webhook response contains the job ID in JSON format as shown below. Elle contiendra un seul ID de travail. Toutefois, le format JSON permettra des améliorations ultérieures potentielles.It contains a single job ID, but the JSON format allows for potential future enhancements.

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

Le client ne peut pas déterminer l’issue du travail du runbook ou de son état d’achèvement à partir du webhook.The client can't determine when the runbook job completes or its completion status from the webhook. Il peut trouver ces informations à l’aide de l’ID du travail et d’un autre mécanisme tel que Windows PowerShell ou l’API Azure Automation.It can find out this information using the job ID with another mechanism, such as Windows PowerShell or the Azure Automation API.

Renouveler un webhookRenew a webhook

Lorsqu’un webhook est créé, il reste valide pendant dix ans, puis expire automatiquement.When a webhook is created, it has a validity time period of ten years, after which it automatically expires. Une fois que le webhook a expiré, vous ne pouvez pas le réactiver.Once a webhook has expired, you can't reactivate it. Vous pouvez uniquement le supprimer, puis le recréer.You can only remove and then recreate it.

Vous pouvez prolonger la durée de validité d’un webhook qui n’a pas encore expiré.You can extend a webhook that has not reached its expiration time. Pour prolonger la durée de validité d’un webhook :To extend a webhook:

  1. Accédez au runbook qui contient le webhook.Navigate to the runbook that contains the webhook.
  2. Sélectionnez Webhooks sous Ressources.Select Webhooks under Resources.
  3. Cliquez sur le webhook dont vous voulez prolonger la durée de validité.Click the webhook that you want to extend.
  4. Dans la page Webhook, choisissez une nouvelle date et une nouvelle heure d’expiration, puis cliquez sur Enregistrer.In the Webhook page, choose a new expiration date and time and click Save.

Exemple de runbookSample runbook

L’exemple de runbook suivant accepte les données du webhook et démarre les machines virtuelles spécifiées dans le corps de la demande.The following sample runbook accepts the webhook data and starts the virtual machines specified in the request body. Pour tester ce runbook, dans votre compte Automation sous Runbooks, cliquez sur Créer un runbook.To test this runbook, in your Automation account under Runbooks, click Create a runbook. Si vous ne savez pas comment créer un runbook, consultez Création d’un runbook.If you don't know how to create a runbook, see Creating a runbook.

Nota

Pour les runbooks PowerShell non graphiques, Add-AzAccount et Add-AzureRMAccount sont des alias de Connect-AzAccount.For non-graphical PowerShell runbooks, Add-AzAccount and Add-AzureRMAccount are aliases for Connect-AzAccount. Vous pouvez utiliser ces cmdlets ou mettre à jour vos modules dans votre compte Automation vers les dernières versions.You can use these cmdlets or you can update your modules in your Automation account to the latest versions. Il est possible que vous deviez mettre à jour vos modules, même si vous venez de créer un compte Automation.You might need to update your modules even if you have just created a new Automation account.

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

# If runbook was called from Webhook, WebhookData will not be null.
if ($WebhookData) {

    # Check header for message to validate request
    if ($WebhookData.RequestHeader.message -eq 'StartedbyContoso')
    {
        Write-Output "Header has required information"}
    else
    {
        Write-Output "Header missing required information";
        exit;
    }

    # Retrieve VMs from Webhook request body
    $vms = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

    # Authenticate to Azure by using the service principal and certificate. Then, set the subscription.

    Write-Output "Authenticating to Azure with service principal and certificate"
    $ConnectionAssetName = "AzureRunAsConnection"
    Write-Output "Get connection asset: $ConnectionAssetName"

    $Conn = Get-AutomationConnection -Name $ConnectionAssetName
            if ($Conn -eq $null)
            {
                throw "Could not retrieve connection asset: $ConnectionAssetName. Check that this asset exists in the Automation account."
            }
            Write-Output "Authenticating to Azure with service principal."
            Add-AzAccount -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint | Write-Output

        # Start each virtual machine
        foreach ($vm in $vms)
        {
            $vmName = $vm.Name
            Write-Output "Starting $vmName"
            Start-AzVM -Name $vm.Name -ResourceGroup $vm.ResourceGroup
        }
}
else {
    # Error
    write-Error "This runbook is meant to be started from an Azure alert webhook only."
}

Tester l’exempleTest the sample

L'exemple suivant utilise Windows PowerShell pour démarrer un Runbook avec un webhook.The following example uses Windows PowerShell to start a runbook with a webhook. Tous les langages qui peuvent envoyer une requête HTTP peuvent utiliser un webhook.Any language that can make an HTTP request can use a webhook. Windows PowerShell est utilisé ici à titre d’exemple.Windows PowerShell is used here as an example.

Le Runbook s'attend à une liste de machines virtuelles au format JSON dans le corps de la requête.The runbook is expecting a list of virtual machines formatted in JSON in the body of the request. Le runbook vérifie également que les en-têtes contiennent un message défini afin de vérifier que l’appelant webhook est valide.The runbook validates as well that the headers contain a defined message to validate that the webhook caller is valid.

$uri = "<webHook Uri>"

$vms  = @(
            @{ Name="vm01";ResourceGroup="vm01"},
            @{ Name="vm02";ResourceGroup="vm02"}
        )
$body = ConvertTo-Json -InputObject $vms
$header = @{ message="StartedbyContoso"}
$response = Invoke-WebRequest -Method Post -Uri $uri -Body $body -Headers $header
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

L’exemple suivant montre le corps de la requête qui est disponible pour le runbook dans la propriété RequestBody de WebhookData.The following example shows the body of the request that is available to the runbook in the RequestBody property of WebhookData. Cette valeur est au format JSON afin d’être compatible avec le format inclus dans le corps de la requête.This value is formatted in JSON to be compatible with the format included in the body of the request.

[
    {
        "Name":  "vm01",
        "ResourceGroup":  "myResourceGroup"
    },
    {
        "Name":  "vm02",
        "ResourceGroup":  "myResourceGroup"
    }
]

L'illustration suivante montre la requête envoyée à partir de Windows PowerShell et sa réponse.The following image shows the request being sent from Windows PowerShell and the resulting response. L’ID de travail est extrait de la réponse et converti en une chaîne.The job ID is extracted from the response and converted to a string.

Bouton Webhooks

Étapes suivantesNext steps