Démarrer un Runbook dans Azure Automation

Article
06/01/2023

Le tableau suivant vous aide à déterminer la méthode de démarrage d'un Runbook dans Azure Automation la plus appropriée à votre scénario. Cet article inclut des informations détaillées sur le démarrage d'un Runbook avec le portail Azure et avec Windows PowerShell. Des informations supplémentaires sur les autres méthodes sont fournies dans différentes documentations accessibles depuis les liens ci-dessous.

Méthode	Caractéristiques
Azure portal	Méthode la plus simple avec une interface utilisateur interactive. Formulaire pour fournir les valeurs de paramètres simples. Suivi aisé de l'état des tâches. Accès authentifié avec connexion à Azure.
Windows PowerShell	Appel à partir de la ligne de commande avec les applets de commande Windows PowerShell. Possibilité d’inclusion dans une fonctionnalité automatisée à plusieurs étapes. Demande authentifiée avec un certificat ou un principal du service / principal d'utilisateur OAuth. Fourniture de valeurs de paramètres simples et complexes. Suivi de l’état des tâches. Client requis pour prendre en charge les applets de commande PowerShell.
API Azure Automation	Méthode la plus souple, mais également la plus complexe. Appel à partir de n'importe quel code personnalisé qui peut envoyer des requêtes HTTP. Requête authentifiée avec un certificat ou un principal du service / principal d'utilisateur Oauth. Fourniture de valeurs de paramètres simples et complexes. Si vous appelez un Runbook Python à l'aide de l'API, la charge utile JSON doit être sérialisée. Suivi de l’état des tâches.
Webhooks	Démarrage d'un Runbook à partir d'une simple requête HTTP. Authentification avec un jeton de sécurité dans l'URL. Le client ne peut pas remplacer les valeurs de paramètre spécifiées lors de la création du webhook. Le Runbook peut définir un paramètre unique qui est rempli avec les détails de la requête HTTP. Aucune possibilité de suivre l’état des tâches via l’URL du Webhook.
Répondre à une alerte Azure	Démarrer un Runbook en réponse à une alerte Azure. Configurer webhook pour Runbook et lien vers l'alerte. Authentification avec un jeton de sécurité dans l'URL.
Planification	Démarrage automatique du runbook selon une planification horaire, quotidienne, hebdomadaire ou mensuelle. Manipulation de la planification via le portail Azure, les applets de commande PowerShell ou les API Azure. Fourniture des valeurs de paramètres à utiliser avec la planification.
À partir d'un autre Runbook	Utilisation d’un Runbook en tant qu’activité d’un autre Runbook. Utile pour les fonctionnalités utilisées par plusieurs Runbooks. Fourniture des valeurs de paramètres au Runbook enfant et utilisation de la sortie dans le Runbook parent.

L’image suivante illustre le processus détaillé du cycle de vie d’un Runbook. Elle présente différents modes de démarrage d’un runbook dans Azure Automation, les composants requis pour que le Runbook Worker hybride exécute des runbooks Azure Automation et les interactions entre les différents composants. Pour en savoir plus sur l’exécution des Runbooks Automation dans votre centre de données, consultez l’article Runbooks Workers hybrides

Runbook Architecture

Manipuler les paramètres d’un runbook

Quand vous démarrez un Runbook à partir du portail Azure ou de Windows PowerShell, l’instruction est envoyée par le biais du service web Azure Automation. Ce service ne prend pas en charge les paramètres comportant des types de données complexes. Si vous devez fournir une valeur pour un paramètre complexe, vous devez l’appeler en ligne à partir d’un autre Runbook, comme décrit dans Runbooks enfants dans Azure Automation.

Le service web Azure Automation offre des fonctionnalités spécifiques pour les paramètres à l’aide de certains types de données (cf. sections suivantes).

Valeurs nommées

Si le paramètre est un type de données [object], vous pouvez utiliser le format JSON suivant pour lui envoyer une liste de valeurs nommées : {Nom1:'Valeur1', Nom2:'Valeur2', Nom3:'Valeur3'}. Ces valeurs doivent avoir des types simples. Le Runbook reçoit le paramètre comme PSCustomObject avec des propriétés correspondant à chaque valeur nommée.

Considérez le Runbook de test suivant qui accepte un paramètre nommé user.

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][object]$user
   )
    $userObject = $user | ConvertFrom-JSON
    if ($userObject.Show) {
        foreach ($i in 1..$userObject.RepeatCount) {
            $userObject.FirstName
            $userObject.LastName
        }
    }
}

Le texte suivant peut être utilisé pour le paramètre user.

{FirstName:'Joe',LastName:'Smith',RepeatCount:'2',Show:'True'}

Il s'ensuit la sortie suivante :

Joe
Smith
Joe
Smith

Tableaux

Si le paramètre est un tableau comme [array] ou [string[]], vous pouvez utiliser le format JSON suivant pour lui envoyer une liste de valeurs : [Valeur1, Valeur2, Valeur3]. Ces valeurs doivent avoir des types simples.

Considérez le Runbook de test suivant qui accepte un paramètre nommé user.

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][array]$user
   )
    if ($user[3]) {
        foreach ($i in 1..$user[2]) {
            $ user[0]
            $ user[1]
        }
    }
}

Le texte suivant peut être utilisé pour le paramètre user.

["Joe","Smith",2,true]

Il s'ensuit la sortie suivante :

Joe
Smith
Joe
Smith

Informations d'identification

Si le paramètre est un type de données PSCredential, vous pouvez fournir le nom d'une ressource d'informations d'identification Azure Automation. Le Runbook récupère la ressource d'informations d'identification portant le nom que vous spécifiez. Le Runbook de test suivant accepte un paramètre nommé credential.

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][PSCredential]$credential
   )
   $credential.UserName
}

Le texte suivant peut être utilisé pour le paramètre user en supposant qu'il existe une ressource d'informations d'identification nommée My Credential.

My Credential

En supposant que le nom d’utilisateur dans les informations d’identification est jsmith, le résultat suivant s’affiche.

jsmith

Démarrer un Runbook avec le portail Azure

Dans le portail Azure, sélectionnez Automation, puis le nom d’un compte Automation.
Dans le volet gauche, sélectionnez Runbooks.
Sur la page Runbooks, sélectionnez un runbook, puis cliquez sur Démarrer.
Si le Runbook possède des paramètres, vous êtes invité à fournir des valeurs, avec une zone de texte pour chaque paramètre. Pour plus d'informations sur les paramètres, consultez Paramètres du Runbook .
Sur le volet Travail, vous pouvez voir l’état du travail du runbook.

Démarrer un Runbook avec PowerShell

Vous pouvez utiliser l’applet de commande Start-AzAutomationRunbook pour démarrer un runbook avec Windows PowerShell. L'exemple de code suivant démarre un Runbook appelé Test-Runbook.

Start-AzAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01"

Start-AzAutomationRunbook retourne un objet de traitement que vous pouvez utiliser pour suivre l’état une fois que le runbook a démarré. Vous pouvez ensuite utiliser cet objet de travail avec Get-AzureAutomationJob pour déterminer l'état du travail et Get-AzureAutomationJobOutput pour récupérer son résultat. L'exemple suivant démarre un runbook appelé Test-Runbook, attend qu'il ait terminé, puis affiche son résultat.

$runbookName = "Test-Runbook"
$ResourceGroup = "ResourceGroup01"
$AutomationAcct = "MyAutomationAccount"

$job = Start-AzAutomationRunbook -AutomationAccountName $AutomationAcct -Name $runbookName -ResourceGroupName $ResourceGroup

$doLoop = $true
While ($doLoop) {
   $job = Get-AzAutomationJob -AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup
   $status = $job.Status
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
}

Get-AzAutomationJobOutput -AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup -Stream Output

Si le Runbook requiert des paramètres, vous devez fournir ceux-ci sous forme de table de hachage. La clé de la table de hachage doit correspondre au nom du paramètre, et la valeur est la valeur du paramètre. L'exemple suivant montre comment démarrer un Runbook avec deux paramètres de chaîne nommés FirstName et LastName, un entier nommé RepeatCount et un paramètre booléen nommé Show. Pour plus d'informations sur les paramètres, consultez Paramètres du Runbook .

$params = @{"FirstName"="Joe";"LastName"="Smith";"RepeatCount"=2;"Show"=$true}
Start-AzAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01" -Parameters $params

Étapes suivantes

Pour en savoir plus sur la gestion des runbooks, voir Gérer les runbooks dans Azure Automation.
Pour plus d’informations sur PowerShell, consultez la documentation PowerShell.
Pour résoudre les problèmes liés à l’exécution de runbooks, voir Résoudre les erreurs avec les runbooks.