Découvrir PowerShell Workflow pour Azure AutomationLearn PowerShell Workflow for Azure Automation

Dans Azure Automation, les runbooks sont implémentés comme des workflows Windows PowerShell, qui sont en réalité des scripts Windows PowerShell qui utilisent Windows Workflow Foundation.Runbooks in Azure Automation are implemented as Windows PowerShell workflows, Windows PowerShell scripts that use Windows Workflow Foundation. Un workflow est une séquence d’étapes programmées et connectées qui effectuent des tâches de longue durée ou requièrent la coordination de plusieurs étapes sur plusieurs appareils ou nœuds gérés.A workflow is a sequence of programmed, connected steps that perform long-running tasks or require the coordination of multiple steps across multiple devices or managed nodes.

Le workflow est écrit avec la syntaxe Windows PowerShell et il est lancé par Windows PowerShell, mais il est traité par Windows Workflow Foundation.While a workflow is written with Windows PowerShell syntax and launched by Windows PowerShell, it is processed by Windows Workflow Foundation. Les avantages d’un workflow par rapport à un script normal incluent la possibilité d’exécuter simultanément une action sur plusieurs appareils et de récupérer automatiquement après une défaillance.The benefits of a workflow over a normal script include simultaneous performance of an action against multiple devices and automatic recovery from failures.

Notes

Un script PowerShell Workflow est très similaire à un script Windows PowerShell. Cependant, il présente des différences significatives qui peuvent être déconcertantes pour un nouvel utilisateur.A PowerShell Workflow script is very similar to a Windows PowerShell script but has some significant differences that can be confusing to a new user. Par conséquent, nous vous recommandons d’écrire vos runbooks à l’aide de PowerShell Workflow uniquement si vous devez utiliser des points de contrôle.Therefore, we recommend that you write your runbooks using PowerShell Workflow only if you need to use checkpoints.

Pour plus d’informations sur les rubriques de cet article, consultez Présentation du workflow Windows PowerShell.For complete details of the topics in this article, see Getting Started with Windows PowerShell Workflow.

Utiliser le mot clé WorkflowUse Workflow keyword

La première étape de la conversion d'un script PowerShell en workflow PowerShell consiste à y intégrer le mot clé Workflow.The first step to converting a PowerShell script to a PowerShell workflow is enclosing it with the Workflow keyword. Un workflow commence par le mot clé Workflow suivi du corps du script entre accolades.A workflow starts with the Workflow keyword followed by the body of the script enclosed in braces. Le nom du workflow suit le mot clé Workflow, comme illustré dans la syntaxe suivante :The name of the workflow follows the Workflow keyword as shown in the following syntax:

Workflow Test-Workflow
{
    <Commands>
}

Le nom du workflow doit correspondre au nom du Runbook Automation.The name of the workflow must match the name of the Automation runbook. Si le runbook est importé, le nom de fichier doit correspondre au nom du workflow et se terminer par .ps1.If the runbook is being imported, then the file name must match the workflow name and must end in .ps1.

Pour ajouter des paramètres au workflow, utilisez le mot clé Param, comme dans un script.To add parameters to the workflow, use the Param keyword just as you would in a script.

Différences entre le code PowerShell Workflow et le code d’un script PowerShellLearn differences between PowerShell Workflow code and PowerShell script code

Le code PowerShell Workflow est quasiment identique à celui d’un script PowerShell, à l’exception de certaines différences peu nombreuses, mais importantes.PowerShell Workflow code looks almost identical to PowerShell script code except for a few significant changes. Les sections suivantes décrivent les modifications que vous devez apporter à un script PowerShell pour l’exécuter dans un workflow.The following sections describe changes that you need to make to a PowerShell script for it to run in a workflow.

ActivitésActivities

Une activité est une tâche incluse dans un workflow qui est exécutée dans un ordre précis.An activity is a specific task in a workflow that is performed in a sequence. Le workflow Windows PowerShell convertit automatiquement la plupart des applets de commande Windows PowerShell en activités lors de son exécution.Windows PowerShell Workflow automatically converts many of the Windows PowerShell cmdlets to activities when it runs a workflow. Lorsque vous spécifiez une de ces applets de commande dans votre Runbook, l’activité correspondante est exécutée par Windows Workflow Foundation.When you specify one of these cmdlets in your runbook, the corresponding activity is run by Windows Workflow Foundation.

Si une applet de commande ne correspond à aucune activité, Windows PowerShell Workflow l’exécute automatiquement au sein d’une activité InlineScript.If a cmdlet has no corresponding activity, Windows PowerShell Workflow automatically runs the cmdlet in an InlineScript activity. Certaines applets de commande sont exclues et ne peuvent pas être utilisées dans un workflow, à moins que vous ne les incluiez explicitement dans un bloc InlineScript.Some cmdlets are excluded and can't be used in a workflow unless you explicitly include them in an InlineScript block. Pour plus d’informations, consultez Utilisation d’activités dans les workflows de script.For more information, see Using Activities in Script Workflows.

Les activités de workflow partagent un ensemble de paramètres communs pour configurer leur opération.Workflow activities share a set of common parameters to configure their operation. Voir about_WorkflowCommonParameters.See about_WorkflowCommonParameters.

Paramètres positionnelsPositional parameters

Vous ne pouvez pas utiliser les paramètres positionnels avec les activités et les applets de commande dans un workflow.You can't use positional parameters with activities and cmdlets in a workflow. Par conséquent, vous devez utiliser des noms de paramètres.Therefore, you must use parameter names. Vous pouvez utiliser le code suivant pour afficher tous les services en cours d’exécution :Consider the following code that gets all running services:

Get-Service | Where-Object {$_.Status -eq "Running"}

Si vous tentez d’exécuter ce code dans un workflow, vous recevez un message du type Parameter set cannot be resolved using the specified named parameters.. Pour corriger ce problème, fournissez le nom du paramètre, comme dans l’exemple suivant :If you try to run this code in a workflow, you receive a message like Parameter set cannot be resolved using the specified named parameters. To correct for this issue, provide the parameter name, as in the following example:

Workflow Get-RunningServices
{
    Get-Service | Where-Object -FilterScript {$_.Status -eq "Running"}
}

Objets désérialisésDeserialized objects

Les objets des workflows sont désérialisés, ce qui signifie que leurs propriétés sont toujours disponibles, mais pas leurs méthodes.Objects in workflows are deserialized, meaning that their properties are still available, but not their methods. Par exemple, vous pouvez utiliser le code PowerShell suivant qui arrête un service à l’aide de la méthode Stop de l’objet Service.For example, consider the following PowerShell code, which stops a service using the Stop method of the Service object.

$Service = Get-Service -Name MyService
$Service.Stop()

Si vous tentez de l’exécuter dans un workflow, vous recevez une erreur indiquant ceci : Method invocation is not supported in a Windows PowerShell Workflow..If you try to run this in a workflow, you receive an error saying Method invocation is not supported in a Windows PowerShell Workflow.

L’une des options consiste à wrapper ces deux lignes de code dans un bloc InlineScript.One option is to wrap these two lines of code in an InlineScript block. Dans ce cas, Service représente un objet de service situé à l’intérieur du bloc.In this case, Service represents a service object within the block.

Workflow Stop-Service
{
    InlineScript {
        $Service = Get-Service -Name MyService
        $Service.Stop()
    }
}

Une autre option consiste à utiliser une autre applet de commande qui a les mêmes fonctionnalités que la méthode, si celle-ci est disponible.Another option is to use another cmdlet that has the same functionality as the method, if one is available. Dans notre exemple, l’applet de commande Stop-Service fournit les mêmes fonctionnalités que la méthode Stop, et vous pouvez utiliser les éléments suivants pour un workflow.In our example, the Stop-Service cmdlet provides the same functionality as the Stop method, and you might use the following code for a workflow.

Workflow Stop-MyService
{
    $Service = Get-Service -Name MyService
    Stop-Service -Name $Service.Name
}

Utiliser InlineScriptUse InlineScript

L'activité InlineScript est utile lorsque vous devez exécuter une ou plusieurs commandes en tant que script PowerShell standard plutôt que workflow PowerShell.TheInlineScript activity is useful when you need to run one or more commands as traditional PowerShell script instead of PowerShell workflow. Alors que les commandes d'un workflow sont envoyées à Windows Workflow Foundation pour être traitées, les commandes d'un bloc InlineScript sont traitées par Windows PowerShell.While commands in a workflow are sent to Windows Workflow Foundation for processing, commands in an InlineScript block are processed by Windows PowerShell.

InlineScript utilise la syntaxe illustrée ci-dessous.InlineScript uses the following syntax shown below.

InlineScript
{
    <Script Block>
} <Common Parameters>

Vous pouvez renvoyer la sortie d'un bloc InlineScript en l'affectant à une variable.You can return output from an InlineScript by assigning the output to a variable. L'exemple suivant arrête un service puis renvoie le nom du service.The following example stops a service and then outputs the service name.

Workflow Stop-MyService
{
    $Output = InlineScript {
        $Service = Get-Service -Name MyService
        $Service.Stop()
        $Service
    }

    $Output.Name
}

Vous pouvez passer des valeurs dans un bloc InlineScript, mais vous devez utiliser le modificateur de portée $Using .You can pass values into an InlineScript block, but you must use $Using scope modifier. L'exemple suivant est identique à l'exemple précédent, sauf que le nom du service est fourni par une variable.The following example is identical to the previous example except that the service name is provided by a variable.

Workflow Stop-MyService
{
    $ServiceName = "MyService"

    $Output = InlineScript {
        $Service = Get-Service -Name $Using:ServiceName
        $Service.Stop()
        $Service
    }

    $Output.Name
}

Même si les activités InlineScript peuvent être critiques dans certains workflows, elles ne prennent pas en charge les constructions de workflow.While InlineScript activities might be critical in certain workflows, they do not support workflow constructs. Vous devez les utiliser seulement si c’est nécessaire pour les raisons suivantes :You should use them only when necessary for the following reasons:

  • Vous ne pouvez pas utiliser de points de contrôle à l’intérieur d’un bloc InlineScript.You can't use checkpoints inside an InlineScript block. Si une défaillance se produit dans le bloc, l’exécution doit reprendre depuis le début du bloc.If a failure occurs within the block, it must resume from the beginning of the block.
  • Vous ne pouvez pas effectuer d’exécution parallèle à l’intérieur d’un bloc InlineScript.You can't use parallel execution inside an InlineScript block.
  • InlineScript affecte l'extensibilité du workflow puisque l'activité maintient la session Windows PowerShell pendant toute la durée du bloc InlineScript.InlineScript affects scalability of the workflow since it holds the Windows PowerShell session for the entire length of the InlineScript block.

Pour plus d’informations sur l’utilisation d’InlineScript, consultez Exécution des commandes Windows PowerShell dans un workflow et about_InlineScript.For more information on using InlineScript, see Running Windows PowerShell Commands in a Workflow and about_InlineScript.

Utiliser le traitement parallèleUse parallel processing

L'un des avantages des workflows Windows PowerShell est la possibilité d'exécuter un ensemble de commandes en parallèle, et non séquentiellement comme avec un script classique.One advantage of Windows PowerShell Workflows is the ability to perform a set of commands in parallel instead of sequentially as with a typical script.

Vous pouvez utiliser le mot clé Parallel pour créer un bloc de script avec plusieurs commandes qui s'exécutent simultanément.You can use the Parallel keyword to create a script block with multiple commands that run concurrently. Pour ce faire, utilisez la syntaxe illustrée ci-dessous.This uses the following syntax shown below. Dans ce cas, Activity1 et Activity2 démarrent en même temps.In this case, Activity1 and Activity2 starts at the same time. Activity3 démarre uniquement quand Activity1 et Activity2 sont toutes deux terminées.Activity3 starts only after both Activity1 and Activity2 have completed.

Parallel
{
    <Activity1>
    <Activity2>
}
<Activity3>

Par exemple, considérez les commandes PowerShell suivantes qui copier plusieurs fichiers vers une destination sur le réseau.For example, consider the following PowerShell commands that copy multiple files to a network destination. Ces commandes sont exécutées séquentiellement afin que le fichier termine la copie avant de démarrer la suivante.These commands are run sequentially so that one file must finish copying before the next is started.

Copy-Item -Path C:\LocalPath\File1.txt -Destination \\NetworkPath\File1.txt
Copy-Item -Path C:\LocalPath\File2.txt -Destination \\NetworkPath\File2.txt
Copy-Item -Path C:\LocalPath\File3.txt -Destination \\NetworkPath\File3.txt

Le workflow suivant exécute ces commandes en parallèle afin qu'elles commencent toutes la copie en même temps.The following workflow runs these same commands in parallel so that they all start copying at the same time. Le message confirmant la fin de l’opération apparaît uniquement une fois toutes les copies effectuées.Only after they are all copied is the completion message displayed.

Workflow Copy-Files
{
    Parallel
    {
        Copy-Item -Path "C:\LocalPath\File1.txt" -Destination "\\NetworkPath"
        Copy-Item -Path "C:\LocalPath\File2.txt" -Destination "\\NetworkPath"
        Copy-Item -Path "C:\LocalPath\File3.txt" -Destination "\\NetworkPath"
    }

    Write-Output "Files copied."
}

Vous pouvez utiliser la construction ForEach -Parallel pour traiter simultanément les commandes de chaque élément d'une collection.You can use the ForEach -Parallel construct to process commands for each item in a collection concurrently. Les éléments de la collection sont traités en parallèle, tandis que les commandes du bloc de script sont exécutées séquentiellement.The items in the collection are processed in parallel while the commands in the script block run sequentially. Ce processus utilise la syntaxe ci-dessous.This process uses the following syntax shown below. Dans ce cas, Activity1 démarre en même temps pour tous les éléments de la collection.In this case, Activity1 starts at the same time for all items in the collection. Pour chaque élément, Activity2 démarre une fois Activity1 terminée.For each item, Activity2 starts after Activity1 is complete. Activity3 démarre uniquement quand Activity1 et Activity2 sont toutes deux terminées pour tous les éléments.Activity3 starts only after both Activity1 and Activity2 have completed for all items. Nous utilisons le paramètre ThrottleLimit pour limiter le parallélisme.We use the ThrottleLimit parameter to limit the parallelism. Une valeur ThrottleLimit trop élevée peut entraîner des problèmes.Too high of a ThrottleLimit can cause problems. La valeur idéale pour le paramètre ThrottleLimit dépend de nombreux facteurs dans votre environnement.The ideal value for the ThrottleLimit parameter depends on many factors in your environment. Commencez par une valeur basse, puis essayez des valeurs de plus en plus élevées jusqu’à ce que vous en trouviez une qui fonctionne pour votre situation.Start with a low value and try different increasing values until you find one that works for your specific circumstance.

ForEach -Parallel -ThrottleLimit 10 ($<item> in $<collection>)
{
    <Activity1>
    <Activity2>
}
<Activity3>

L'exemple suivant est similaire à l'exemple précédent concernant la copie de fichiers en parallèle.The following example is similar to the previous example copying files in parallel. Dans ce cas, un message s'affiche pour chaque fichier après la copie.In this case, a message is displayed for each file after it copies. Le message confirmant la fin de l’opération apparaît uniquement une fois toutes les copies effectuées.Only after they are all copied is the final completion message displayed.

Workflow Copy-Files
{
    $files = @("C:\LocalPath\File1.txt","C:\LocalPath\File2.txt","C:\LocalPath\File3.txt")

    ForEach -Parallel -ThrottleLimit 10 ($File in $Files)
    {
        Copy-Item -Path $File -Destination \\NetworkPath
        Write-Output "$File copied."
    }

    Write-Output "All files copied."
}

Notes

Nous vous déconseillons d'exécuter des Runbooks enfants en parallèle car les résultats obtenus ne sont pas fiables.We do not recommend running child runbooks in parallel since this has been shown to give unreliable results. Parfois, la sortie du runbook enfant n’apparaît pas, et les paramètres d’un runbook enfant peuvent affecter les autres runbooks enfants parallèles.The output from the child runbook sometimes does not show up, and settings in one child runbook can affect the other parallel child runbooks. Les variables comme VerbosePreference et WarningPreference, entre autres, peuvent ne pas se propager aux runbooks enfants.Variables such as VerbosePreference, WarningPreference, and others might not propagate to the child runbooks. De plus, si le runbook enfant modifie ces valeurs, celles-ci peuvent ne pas être correctement restaurées après l’appel.And if the child runbook changes these values, they might not be properly restored after invocation.

Utiliser des points de contrôle dans un workflowUse checkpoints in a workflow

Un point de contrôle est un instantané de l’état actuel du workflow qui inclut la valeur actuelle des variables et toute sortie générée à ce stade.A checkpoint is a snapshot of the current state of the workflow that includes the current values for variables and any output generated to that point. Si un workflow se termine par une erreur ou s’il est suspendu, il démarrera à partir de son dernier point de contrôle lors de sa prochaine exécution, au lieu de commencer au début.If a workflow ends in error or is suspended, it starts from its last checkpoint the next time it runs, instead of starting at the beginning.

Vous pouvez définir un point de contrôle dans un workflow avec l'activité Checkpoint-Workflow.You can set a checkpoint in a workflow with the Checkpoint-Workflow activity. Azure Automation dispose d’une fonctionnalité appelée répartition équilibrée, grâce à laquelle tout runbook s’exécutant depuis plus de 3 heures est déchargé pour permettre l’exécution des autres runbooks.Azure Automation has a feature called fair share, for which any runbook that runs for three hours is unloaded to allow other runbooks to run. À la fin, le runbook déchargé est rechargé.Eventually, the unloaded runbook is reloaded. À ce moment-là, il reprend son exécution à partir du dernier point de contrôle exécuté dans le runbook.When it is, it resumes execution from the last checkpoint taken in the runbook.

Pour que le runbook s’exécute jusqu’au bout, vous devez ajouter des points de contrôle à des intervalles inférieurs à 3 heures.To guarantee that the runbook eventually completes, you must add checkpoints at intervals that run for less than three hours. Si un point de contrôle est ajouté lors de chaque exécution, et si le runbook est évincé au bout de 3 heures en raison d’une erreur, le runbook sera exécuté indéfiniment.If during each run a new checkpoint is added, and if the runbook is evicted after three hours due to an error, the runbook is resumed indefinitely.

Dans l’exemple suivant, une exception se produit après qu’Activity2 a provoqué l’arrêt du workflow.In the following example, an exception occurs after Activity2, causing the workflow to end. Lorsque le workflow est réexécuté, il commence par exécuter Activity2, puisque cette activité vient immédiatement après le dernier point de contrôle défini.When the workflow is run again, it starts by running Activity2, since this activity was just after the last checkpoint set.

<Activity1>
Checkpoint-Workflow
<Activity2>
<Exception>
<Activity3>

Définissez les points de contrôle d’un workflow après les activités qui peuvent être sujettes à une exception et qui ne doivent pas être réexécutées à la reprise du workflow.Set checkpoints in a workflow after activities that might be prone to exception and should not be repeated if the workflow is resumed. Par exemple, votre workflow peut créer une machine virtuelle.For example, your workflow might create a virtual machine. Vous pouvez définir un point de contrôle avant et après les commandes de création de la machine virtuelle.You can set a checkpoint both before and after the commands to create the virtual machine. En cas d’échec de la création, les commandes sont répétées si le workflow est redémarré.If the creation fails, then the commands are repeated if the workflow is started again. Si le workflow échoue après que la création a réussi, la machine virtuelle n’est pas recréée à la reprise du workflow.If the workflow fails after the creation succeeds, the virtual machine is not created again when the workflow is resumed.

L'exemple suivant copie plusieurs fichiers vers un emplacement réseau et définit un point de contrôle après chaque fichier.The following example copies multiple files to a network location and sets a checkpoint after each file. Si l’emplacement réseau est perdu, le workflow s’arrête en générant une erreur.If the network location is lost, then the workflow ends in error. Lorsqu’il est redémarré, il reprend au dernier point de contrôle.When it is started again, it resumes at the last checkpoint. Seuls les fichiers qui ont déjà été copiés sont ignorés.Only the files that have already been copied are skipped.

Workflow Copy-Files
{
    $files = @("C:\LocalPath\File1.txt","C:\LocalPath\File2.txt","C:\LocalPath\File3.txt")

    ForEach ($File in $Files)
    {
        Copy-Item -Path $File -Destination \\NetworkPath
        Write-Output "$File copied."
        Checkpoint-Workflow
    }

    Write-Output "All files copied."
}

Comme les informations d’identification du nom d’utilisateur ne sont pas conservées après l’appel de l’activité Suspend-Workflow ou après le dernier point de contrôle, vous devez définir les informations d’identification comme « null », puis les récupérer à nouveau à partir du magasin de ressources après l’activité Suspend-Workflow ou après l’appel du point de contrôle.Because user name credentials are not persisted after you call the Suspend-Workflow activity or after the last checkpoint, you need to set the credentials to null and then retrieve them again from the asset store after Suspend-Workflow or checkpoint is called. Sinon, le message d’erreur suivant peut s’afficher : The workflow job cannot be resumed, either because persistence data could not be saved completely, or saved persistence data has been corrupted. You must restart the workflow.Otherwise, you might receive the following error message: The workflow job cannot be resumed, either because persistence data could not be saved completely, or saved persistence data has been corrupted. You must restart the workflow.

Le même code ci-dessous montre comment traiter ce problème dans vos runbooks PowerShell Workflow.The following same code demonstrates how to handle this situation in your PowerShell Workflow runbooks.

workflow CreateTestVms
{
    $Cred = Get-AzAutomationCredential -Name "MyCredential"
    $null = Connect-AzAccount -Credential $Cred

    $VmsToCreate = Get-AzAutomationVariable -Name "VmsToCreate"

    foreach ($VmName in $VmsToCreate)
        {
        # Do work first to create the VM (code not shown)

        # Now add the VM
        New-AzVM -VM $Vm -Location "WestUs" -ResourceGroupName "ResourceGroup01"

        # Checkpoint so that VM creation is not repeated if workflow suspends
        $Cred = $null
        Checkpoint-Workflow
        $Cred = Get-AzAutomationCredential -Name "MyCredential"
        $null = Connect-AzAccount -Credential $Cred
        }
}

Notes

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. L’utilisation de ces applets de commande n’est pas nécessaire si vous vous authentifiez à l’aide d’un compte d’identification configuré avec un principal de service.Use of these cmdlets is not required if you are authenticating using a Run As account configured with a service principal.

Pour plus d'informations sur les points de contrôle, consultez Ajout de points de contrôle à un workflow de script.For more information about checkpoints, see Adding Checkpoints to a Script Workflow.

Étapes suivantesNext steps