Aprender sobre os principais conceitos de Fluxo de Trabalho do Windows PowerShell para runbooks de AutomaçãoLearning key Windows PowerShell Workflow concepts for Automation runbooks

Os runbooks na Automação do Azure são implementados como Fluxos de Trabalho do Windows PowerShell.Runbooks in Azure Automation are implemented as Windows PowerShell Workflows. Um fluxo de trabalho do Windows PowerShell é semelhante a um script do Windows PowerShell, mas tem algumas diferenças significativas que podem ser confusas para um novo usuário.A Windows PowerShell Workflow is similar to a Windows PowerShell script but has some significant differences that can be confusing to a new user. Embora este artigo sirva para ajudar você a escrever runbooks usando o Fluxo de Trabalho do PowerShell, recomendamos que você escreva os runbooks usando o PowerShell, a menos que você precise de pontos de verificação.While this article is intended to help you write runbooks using PowerShell workflow, we recommend you write runbooks using PowerShell unless you need checkpoints. Há diversas diferenças de sintaxe quando se cria runbooks de Fluxo de trabalho do PowerShell, e essas diferenças exigem um pouco mais de trabalho para escrever fluxos de trabalho efetivos.There are several syntax differences when authoring PowerShell Workflow runbooks and these differences require a bit more work to write effective workflows.

Um fluxo de trabalho é uma sequência de etapas programadas e conectadas que executam tarefas de longa duração ou exigem a coordenação de várias etapas em vários dispositivos ou nós gerenciados.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. Os benefícios de um fluxo de trabalho comparado com um script normal incluem a capacidade de realizar simultaneamente uma ação em vários dispositivos e a capacidade de se recuperar automaticamente de falhas.The benefits of a workflow over a normal script include the ability to simultaneously perform an action against multiple devices and the ability to automatically recover from failures. Um Fluxo de Trabalho do Windows PowerShell é um script do Windows PowerShell que usa o Windows Workflow Foundation.A Windows PowerShell Workflow is a Windows PowerShell script that uses Windows Workflow Foundation. Embora o fluxo de trabalho seja escrito com a sintaxe do Windows PowerShell e inicializado pelo Windows PowerShell, ele é processado pelo Windows Workflow Foundation.While the workflow is written with Windows PowerShell syntax and launched by Windows PowerShell, it is processed by Windows Workflow Foundation.

Para obter detalhes completos sobre os tópicos nesse artigo, consulte Introdução ao fluxo de trabalho do Windows PowerShell.For complete details on the topics in this article, see Getting Started with Windows PowerShell Workflow.

Estrutura básica de um fluxo de trabalhoBasic structure of a workflow

A primeira etapa para converter um script do PowerShell para um fluxo de trabalho do PowerShell é circunscrevê-lo com a palavra-chave Workflow .The first step to converting a PowerShell script to a PowerShell workflow is enclosing it with the Workflow keyword. Um fluxo de trabalho começa com a palavra-chave Workflow seguida do corpo do script entre chaves.A workflow starts with the Workflow keyword followed by the body of the script enclosed in braces. O nome do fluxo de trabalho segue a palavra-chave Workflow, conforme mostra a sintaxe a seguir:The name of the workflow follows the Workflow keyword as shown in the following syntax:

Workflow Test-Workflow
{
    <Commands>
}

O nome do fluxo de trabalho deve corresponder ao nome do runbook de automação.The name of the workflow must match the name of the Automation runbook. Se o runbook está sendo importado, o nome do arquivo deve corresponder ao nome do fluxo de trabalho e deve terminar em .ps1.If the runbook is being imported, then the filename must match the workflow name and must end in .ps1.

Para adicionar parâmetros ao fluxo de trabalho, use a palavra-chave Param , exatamente como faria para um script.To add parameters to the workflow, use the Param keyword just as you would to a script.

Alterações de códigoCode changes

O código de fluxo de trabalho do PowerShell é praticamente idêntico ao código de script do PowerShell, exceto por algumas alterações significativas.PowerShell workflow code looks almost identical to PowerShell script code except for a few significant changes. As seções a seguir descrevem as alterações que você precisa fazer em um script do PowerShell para ele para executar em um fluxo de trabalho.The following sections describe changes that you need to make to a PowerShell script for it to run in a workflow.

AtividadesActivities

Uma atividade é uma tarefa específica em um fluxo de trabalho.An activity is a specific task in a workflow. Assim como um script é composto de um ou mais comandos, um fluxo de trabalho é composto de uma ou mais atividades que são executadas em uma sequência.Just as a script is composed of one or more commands, a workflow is composed of one or more activities that are carried out in a sequence. O fluxo de trabalho do Windows PowerShell converte automaticamente muitos dos cmdlets do Windows PowerShell para atividades ao executar um fluxo de trabalho.Windows PowerShell Workflow automatically converts many of the Windows PowerShell cmdlets to activities when it runs a workflow. Quando você especifica um desses cmdlets em seu runbook, a atividade correspondente é executada pelo Windows Workflow Foundation.When you specify one of these cmdlets in your runbook, the corresponding activity is run by Windows Workflow Foundation. Para esses cmdlets sem uma atividade correspondente, o Fluxo de Trabalho do Windows PowerShell executa o cmdlet automaticamente dentro de uma atividade de InlineScript .For those cmdlets without a corresponding activity, Windows PowerShell Workflow automatically runs the cmdlet within an InlineScript activity. Há um conjunto de cmdlets que são excluídos e não podem ser usados em um fluxo de trabalho, a menos que você o inclua explicitamente em um bloco de InlineScript.There is a set of cmdlets that are excluded and cannot be used in a workflow unless you explicitly include them in an InlineScript block. Para obter mais detalhes sobre esses conceitos, confira Usando atividades em fluxos de trabalho de script.For further details on these concepts, see Using Activities in Script Workflows.

As atividades de fluxo de trabalho compartilham um conjunto de parâmetros comuns para configurar suas operações.Workflow activities share a set of common parameters to configure their operation. Para obter detalhes sobre os parâmetros comuns do fluxo de trabalho, consulte about_WorkflowCommonParameters.For details about the workflow common parameters, see about_WorkflowCommonParameters.

Parâmetros posicionaisPositional parameters

Você não pode usar parâmetros posicionais com atividades e cmdlets em um fluxo de trabalho.You can't use positional parameters with activities and cmdlets in a workflow. Tudo o que isso significa é que você deve usar nomes de parâmetro.All this means is that you must use parameter names.

Por exemplo, considere o código a seguir que obtém todos os serviços em execução.For example, consider the following code that gets all running services.

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

Se você tentar executar esse mesmo código em um fluxo de trabalho, receberá uma mensagem como "O conjunto de parâmetros não pode ser resolvido usando os parâmetros nomeados especificados".If you try to run this same code in a workflow, you receive a message like "Parameter set cannot be resolved using the specified named parameters." Para corrigir isso, basta fornecer o nome do parâmetro como demonstrado a seguir.To correct this, provide the parameter name as in the following.

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

Objetos desserializadosDeserialized objects

Os objetos em fluxos de trabalho são desserializados.Objects in workflows are deserialized. Isso significa que suas propriedades ainda estão disponíveis, mas não seus métodos.This means that their properties are still available, but not their methods. Por exemplo, considere código do PowerShell a seguir que para um serviço usando o método Stop do objeto Service.For example, consider the following PowerShell code that stops a service using the Stop method of the Service object.

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

Se você tentar executá-lo em um fluxo de trabalho, receberá um erro dizendo "Não há suporte para a invocação de método em um Fluxo de Trabalho do Windows PowerShell".If you try to run this in a workflow, you receive an error saying "Method invocation is not supported in a Windows PowerShell Workflow."

Uma opção é encapsular essas duas linhas de código em um bloco InlineScript; neste caso, $Service seria um objeto de serviço dentro do bloco.One option is to wrap these two lines of code in an InlineScript block in which case $Service would be a service object within the block.

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

Outra opção é usar outro cmdlet que executa a mesma funcionalidade que o método, se houver um disponível.Another option is to use another cmdlet that performs the same functionality as the method, if one is available. No nosso exemplo, o cmdlet Stop-Service fornece a mesma funcionalidade que o método Stop, sendo que você pode usar o demonstrado a seguir para um fluxo de trabalho.In our sample, the Stop-Service cmdlet provides the same functionality as the Stop method, and you could use the following for a workflow.

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

InlineScriptInlineScript

A atividade InlineScript é útil quando você precisa executar um ou mais comandos como um script do PowerShell tradicional em vez do fluxo de trabalho do PowerShell.The InlineScript activity is useful when you need to run one or more commands as traditional PowerShell script instead of PowerShell workflow. Enquanto os comandos em um fluxo de trabalho são enviados ao Windows Workflow Foundation para processamento, os comandos em um bloco de InlineScript são processados pelo 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.

O InlineScript usa a sintaxe mostrada abaixo.InlineScript uses the following syntax shown below.

InlineScript
{
    <Script Block>
} <Common Parameters>

Você pode retornar a saída de um InlineScript atribuindo a saída a uma variável.You can return output from an InlineScript by assigning the output to a variable. O exemplo a seguir para um serviço e, em seguida, gera o nome do serviço.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
}

Você pode passar valores para um bloco InlineScript, mas deve usar o modificador de escopo $Using .You can pass values into an InlineScript block, but you must use $Using scope modifier. O exemplo a seguir é idêntico ao exemplo anterior, exceto que o nome do serviço é fornecido por uma variável.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
}

Embora as atividades InlineScript possam ser essenciais em determinados fluxos de trabalho, elas não dão suporte a construtores de fluxo de trabalho e devem ser usadas somente quando necessário pelos seguintes motivos:While InlineScript activities may be critical in certain workflows, they do not support workflow constructs and should only be used when necessary for the following reasons:

  • Não é possível usar pontos de verificação dentro de um bloco InlineScript.You cannot use checkpoints inside an InlineScript block. Se uma falha ocorre dentro do bloco, ele deve ser retomado desde o início do bloco.If a failure occurs within the block, it must be resumed from the beginning of the block.
  • Não é possível usar a execução paralela dentro de um InlineScriptBlock.You cannot use parallel execution inside an InlineScriptBlock.
  • O InlineScript afeta a escalabilidade do fluxo de trabalho, uma vez que retém a sessão do Windows PowerShell por toda a duração do bloco de InlineScript.InlineScript affects scalability of the workflow since it holds the Windows PowerShell session for the entire length of the InlineScript block.

Para obter mais informações sobre como usar o InlineScript, consulte Executando comandos do Windows PowerShell em um fluxo de trabalho e about_InlineScript.For more information on using InlineScript, see Running Windows PowerShell Commands in a Workflow and about_InlineScript.

Processamento paraleloParallel processing

Uma vantagem dos Fluxos de Trabalho do Windows PowerShell é a capacidade de executar um conjunto de comandos em paralelo em vez de sequencialmente como com um script típico.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.

Você pode usar a palavra-chave Parallel para criar um bloco de script com vários comandos que são executados simultaneamente.You can use the Parallel keyword to create a script block with multiple commands that run concurrently. Isso usa a sintaxe a seguir, mostrada abaixo.This uses the following syntax shown below. Nesse caso, Activity1 e a Activity2 começarão simultaneamente.In this case, Activity1 and Activity2 starts at the same time. A Activity3 começará somente após a conclusão da Activity1 e da Activity2.Activity3 starts only after both Activity1 and Activity2 have completed.

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

Por exemplo, considere os seguintes comandos do PowerShell que copiam vários arquivos para um destino de rede.For example, consider the following PowerShell commands that copy multiple files to a network destination. Esses comandos são executados em sequência, de forma que a cópia de um arquivo deve terminar antes que a do próximo seja iniciada.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

O fluxo de trabalho a seguir executa esses mesmos comandos em paralelo para que todos eles comecem a copiar ao mesmo tempo.The following workflow runs these same commands in parallel so that they all start copying at the same time. A mensagem de conclusão será exibida somente depois que todos eles tiverem sido copiados.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."
}

Você pode usar o construct ForEach-Parallel para processar comandos de cada item em uma coleção simultaneamente.You can use the ForEach -Parallel construct to process commands for each item in a collection concurrently. Os itens na coleção são processados em paralelo, enquanto os comandos no bloco de script são executados em sequência.The items in the collection are processed in parallel while the commands in the script block run sequentially. Isso usa a sintaxe a seguir, mostrada abaixo.This uses the following syntax shown below. Nesse caso, Activity1 será iniciada simultaneamente para todos os itens na coleção.In this case, Activity1 starts at the same time for all items in the collection. Para cada item, a Activity2 será iniciada após a conclusão da Activity1.For each item, Activity2 starts after Activity1 is complete. A Activity3 começará somente depois da conclusão da Activity1 e Activity2 para todos os itens.Activity3 starts only after both Activity1 and Activity2 have completed for all items. Nós usamos o parâmetro ThrottleLimit para limitar o paralelismo.We use the ThrottleLimit parameter to limit the parallelism. Muito acima de um ThrottleLimit pode causar problemas.Too high of a ThrottleLimit can cause problems. O valor ideal para o ThrottleLimit parâmetro depende de muitos fatores no ambiente.The ideal value for the ThrottleLimit parameter depends on many factors in your environment. Você deve experimentar começando com um valor baixo e tentar diferentes valores crescentes até localizar um que funcione para a sua circunstância específica.You should try 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>

O exemplo a seguir é semelhante ao exemplo anterior copiando os arquivos em paralelo.The following example is similar to the previous example copying files in parallel. Nesse caso, uma mensagem é exibida para cada arquivo depois de copiar.In this case, a message is displayed for each file after it copies. Somente depois que todos estiverem completamente copiados a mensagem de conclusão final é exibida.Only after they are all completely 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."
}

Observação

Não recomendamos a execução de runbooks filho em paralelo, uma vez que isso demonstrou fornecer resultados não confiáveis.We do not recommend running child runbooks in parallel since this has been shown to give unreliable results. Às vezes, a saída do runbook filho não é exibida e as configurações em um runbook filho podem afetar os outros runbooks filho paralelos.The output from the child runbook sometimes does not show up, and settings in one child runbook can affect the other parallel child runbooks. Variáveis como $VerbosePreference, $WarningPreference, e outras, podem não ser propagadas para os runbooks filho.Variables such as $VerbosePreference, $WarningPreference, and others may not be propagated to the child runbooks. E se o runbook filho alterar esses valores, talvez não sejam restaurados adequadamente após a invocação.And if the child runbook changes these values, they may not be properly restored after invocation.

Pontos de verificaçãoCheckpoints

Um ponto de verificação é um instantâneo do estado atual do fluxo de trabalho que inclui o valor atual de variáveis e as saídas geradas para aquele ponto.A checkpoint is a snapshot of the current state of the workflow that includes the current value for variables and any output generated to that point. Se um fluxo de trabalho terminar com erro ou se for suspenso, na próxima vez que for executado, ele iniciará em seu último ponto de verificação e não no início do fluxo de trabalho.If a workflow ends in error or is suspended, then the next time it is run it will start from its last checkpoint instead of the start of the workflow. Você pode definir um ponto de verificação em um fluxo de trabalho com a atividade Checkpoint-Workflow .You can set a checkpoint in a workflow with the Checkpoint-Workflow activity. A automação do Azure tem um recurso chamado justa, onde qualquer runbook que é executado por 3 horas é descarregado para permitir que outros runbooks para serem executados.Azure Automation has a feature called fair share, where any runbook that runs for 3 hours is unloaded to allow other runbooks to run. Eventualmente, o runbook descarregado será recarregado e quando ele estiver, ele retomará a execução do último ponto de verificação executada no runbook.Eventually, the unloaded runbook will be reloaded, and when it is, it will resume execution from the last checkpoint taken in the runbook. Para garantir que o runbook será concluída, você deve adicionar os pontos de verificação em intervalos que são executados por menos de 3 horas.In order to guarantee that the runbook will eventually complete, you must add checkpoints at intervals that run for less than 3 hours. Se durante cada execução de um novo ponto de verificação é adicionado, e se o runbook obtém removido após três horas devido a um erro, em seguida, o runbook será retomado indefinidamente.If during each run a new checkpoint is added, and if the runbook gets evicted after 3 hours due to an error, then the runbook will be resumed indefinitely.

No código de exemplo a seguir, uma exceção ocorre após Activity2, fazendo com que o fluxo de trabalho seja encerrado.In the following sample code, an exception occurs after Activity2 causing the workflow to end. Quando o fluxo de trabalho é executado novamente, ele começa pela execução de Activity2, já que isso foi logo após o último ponto de verificação definido.When the workflow is run again, it starts by running Activity2 since this was just after the last checkpoint set.

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

Você deve definir pontos de verificação em um fluxo de trabalho para depois de atividades que possam estar sujeitas a exceção e não devam ser repetidas se o fluxo de trabalho for retomado.You should set checkpoints in a workflow after activities that may be prone to exception and should not be repeated if the workflow is resumed. Por exemplo, o fluxo de trabalho pode criar uma máquina virtual.For example, your workflow may create a virtual machine. Você pode definir um ponto de verificação antes e depois dos comandos para criar a máquina virtual.You could set a checkpoint both before and after the commands to create the virtual machine. Se a criação falhar, os comandos serão repetidos se o fluxo de trabalho for iniciado novamente.If the creation fails, then the commands would be repeated if the workflow is started again. Se o fluxo de trabalho falhar após a criação ser bem-sucedida, a máquina virtual não será criada novamente quando o fluxo de trabalho for retomado.If the workflow fails after the creation succeeds, then the virtual machine will not be created again when the workflow is resumed.

O exemplo a seguir copia vários arquivos para um local de rede e define um ponto de verificação depois de cada arquivo.The following example copies multiple files to a network location and sets a checkpoint after each file. Se o local de rede for perdido, o fluxo de trabalho terminará em erro.If the network location is lost, then the workflow ends in error. Quando ele for iniciado novamente, ele retomará do último ponto de verificação, o que significa que somente os arquivos que já tiverem sido copiados serão ignorados.When it is started again, it will resume at the last checkpoint meaning that 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."
}

Como as credenciais do nome de usuário não são mantidas depois de chamar a atividade Suspend-Workflow ou após o último ponto de verificação, você precisa definir as credenciais para null e recuperá-las novamente no armazenamento de ativos após Suspend-Workflow ou o ponto de verificação ser chamado.Because username 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. Caso contrário, a seguinte mensagem de erro será exibida: O trabalho de fluxo de trabalho não pode ser retomado porque os dados de persistência não puderam ser salvos completamente, ou os dados de persistência salvos foram corrompidos. Você deve reiniciar o fluxo de trabalho.Otherwise, you may 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.

O mesmo código a seguir demonstra como lidar com isso em seus runbooks do Fluxo de Trabalho do PowerShell.The following same code demonstrates how to handle this in your PowerShell Workflow runbooks.

workflow CreateTestVms
{
    $Cred = Get-AzureAutomationCredential -Name "MyCredential"
    $null = Connect-AzureRmAccount -Credential $Cred

    $VmsToCreate = Get-AzureAutomationVariable -Name "VmsToCreate"

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

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

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

Importante

Connect-AzureRmAccount agora é um alias para Connect-AzureRMAccount.Add-AzureRmAccount is now an alias for Connect-AzureRMAccount. Ao pesquisar sua biblioteca de itens, se você não vir Connect-AzureRMAccount, você pode usar Connect-AzureRmAccount, ou você pode atualizar seus módulos em sua Conta de Automação.When searching your library items, if you do not see Connect-AzureRMAccount, you can use Add-AzureRmAccount, or you can update your modules in your Automation Account.

Isso não é necessário se você estiver autenticando usando uma conta Executar como configurada com uma entidade de serviço.This is not required if you are authenticating using a Run As account configured with a service principal.

Para saber mais sobre pontos de verificação, confira Adicionando pontos de verificação a um Fluxo de Trabalho de script.For more information about checkpoints, see Adding Checkpoints to a Script Workflow.

Próximas etapasNext steps