Aprender sobre o Fluxo de Trabalho do PowerShell para a Automação do AzureLearn PowerShell Workflow for Azure Automation

Os runbooks na Automação do Azure são implementados como fluxos de trabalho do Windows PowerShell, scripts do Windows PowerShell que usam o Windows Workflow Foundation.Runbooks in Azure Automation are implemented as Windows PowerShell workflows, Windows PowerShell scripts that use Windows Workflow Foundation. Um fluxo de trabalho é uma sequência de etapas programadas e conectadas que executam tarefas de execução longa 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.

Embora um fluxo de trabalho seja escrito com a sintaxe do Windows PowerShell e inicializado pelo Windows PowerShell, ele é processado pelo Windows Workflow Foundation.While a workflow is written with Windows PowerShell syntax and launched by Windows PowerShell, it is processed by Windows Workflow Foundation. 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 simultaneous performance of an action against multiple devices and automatic recovery from failures.

Observação

Um Fluxo de Trabalho do PowerShell é muito semelhante a um script do Windows PowerShell, mas tem algumas diferenças significativas que podem ser confusas para um novo usuário.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. Portanto, recomendamos que você escreva seus runbooks usando o Fluxo de Trabalho do PowerShell somente se precisar usar pontos de verificação.Therefore, we recommend that you write your runbooks using PowerShell Workflow only if you need to use checkpoints.

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

Usar palavra-chave de fluxo de trabalhoUse Workflow keyword

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 precisa corresponder ao nome do fluxo de trabalho e terminar em .ps1.If the runbook is being imported, then the file name 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 in a script.

Aprenda as diferenças entre o código de fluxo de trabalho do PowerShell e código de script do PowerShellLearn differences between PowerShell Workflow code and PowerShell script code

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 que é executada em uma sequência.An activity is a specific task in a workflow that is performed 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.

Se um cmdlet não tem nenhuma atividade correspondente, o Fluxo de Trabalho do Windows PowerShell executa o cmdlet automaticamente dentro de uma atividade InlineScript.If a cmdlet has no corresponding activity, Windows PowerShell Workflow automatically runs the cmdlet in an InlineScript activity. Alguns cmdlets são excluídos e não podem ser usados em um fluxo de trabalho, a menos que você os inclua explicitamente em um bloco de InlineScript.Some cmdlets are excluded and can't be used in a workflow unless you explicitly include them in an InlineScript block. Para obter mais informações, confira Usando atividades em fluxos de trabalho de script.For more information, 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. Confira about_WorkflowCommonParameters.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. Portanto, você precisa usar nomes de parâmetro.Therefore, you must use parameter names. Considere o seguinte código, que obtém todos os serviços em execução:Consider the following code that gets all running services:

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

Se você tentar executar esse código em um fluxo de trabalho, receberá uma mensagem como Parameter set cannot be resolved using the specified named parameters. Para corrigir esse problema, forneça o nome do parâmetro, como no seguinte exemplo: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"}
}

Objetos desserializadosDeserialized objects

Os objetos nos fluxos de trabalho são desserializados, o que significa que suas propriedades ainda estão disponíveis, mas os métodos delas não estão.Objects in workflows are deserialized, meaning that their properties are still available, but not their methods. Por exemplo, considere o código do PowerShell a seguir, que interrompe um serviço usando o método Stop do objeto 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()

Se você tentar executá-lo em um fluxo de trabalho, receberá um erro com a mensagem 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.

Uma opção é encapsular essas duas linhas de código em um bloco InlineScript.One option is to wrap these two lines of code in an InlineScript block. Nesse caso, Service representa um objeto de serviço dentro do bloco.In this case, Service represents a service object within the block.

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

Outra opção é usar outro cmdlet que tenha a mesma funcionalidade que o método, se houver um disponível.Another option is to use another cmdlet that has 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 código demonstrado a seguir para um fluxo de trabalho.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
}

Usar InlineScriptUse InlineScript

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.TheInlineScript 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 de InlineScript possam ser críticas em determinados fluxos de trabalho, elas não são compatíveis com constructos de fluxo de trabalho.While InlineScript activities might be critical in certain workflows, they do not support workflow constructs. Você deve usá-las somente quando necessário, pelos seguintes motivos:You should use them only when necessary for the following reasons:

  • Não é possível usar pontos de verificação dentro de um bloco InlineScript.You can't use checkpoints inside an InlineScript block. Se uma falha ocorrer dentro do bloco, ele precisará retomar desde o início do bloco.If a failure occurs within the block, it must resume from the beginning of the block.
  • Não é possível usar a execução paralela dentro de um bloco InlineScript.You can't use parallel execution inside an InlineScript block.
  • 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.

Usar processamento paraleloUse parallel 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 constructo 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. Esse processo usa a sintaxe a seguir, mostrada abaixo.This process 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. Comece com um valor baixo e experimente valores diferentes crescentes até encontrar um que funcione para a sua circunstância específica.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. A mensagem de conclusão final será exibida somente depois que todos eles tiverem sido copiados.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."
}

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 might not propagate to the child runbooks. E se o runbook filho alterar esses valores, eles talvez não sejam restaurados adequadamente após a invocação.And if the child runbook changes these values, they might not be properly restored after invocation.

Usar pontos de verificação em um fluxo de trabalhoUse checkpoints in a workflow

Um ponto de verificação é um instantâneo do estado atual do fluxo de trabalho que inclui os valores atuais 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 values for variables and any output generated to that point. Se um fluxo de trabalho terminar com erro ou for suspenso, ele será iniciado do seu último ponto de verificação na próxima vez em que for executado, em vez de começar do início.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.

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 fair share, com o qual qualquer runbook executado por três horas é descarregado para permitir que outros runbooks sejam executados.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. Eventualmente, o runbook descarregado é recarregado.Eventually, the unloaded runbook is reloaded. Quando isso ocorre, ele retoma a execução do último ponto de verificação feito no runbook.When it is, it resumes execution from the last checkpoint taken in the runbook.

Para garantir que o runbook seja concluído eventualmente, você precisa adicionar pontos de verificação em intervalos executados por menos de três horas.To guarantee that the runbook eventually completes, you must add checkpoints at intervals that run for less than three hours. Se durante cada execução um novo ponto de verificação for adicionado e se o runbook for removido após três horas devido a um erro, o processamento do runbook será retomado indefinidamente.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.

No exemplo a seguir, uma exceção ocorre após Activity2, fazendo com que o fluxo de trabalho seja encerrado.In the following example, 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 essa atividade foi logo após o último ponto de verificação definido.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>

Defina pontos de verificação em um fluxo de trabalho após atividades que possam estar sujeitas a exceção e não devam ser repetidas se o fluxo de trabalho for retomado.Set checkpoints in a workflow after activities that might 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 might create a virtual machine. Você pode definir um ponto de verificação antes e depois dos comandos para criar a máquina virtual.You can 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 are 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, the virtual machine is not 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 é iniciado novamente, ele continua no último ponto de verificação.When it is started again, it resumes at the last checkpoint. Somente os arquivos que já foram copiados são ignorados.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 do repositório de ativos após Suspend-Workflow ou o ponto de verificação ser chamado.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. Caso contrário, a seguinte mensagem de erro poderá ser exibida: 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.

O mesmo código a seguir demonstra como lidar com essa situação em seus runbooks do Fluxo de Trabalho do PowerShell.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
        }
}

Observação

Para runbooks não gráficos do PowerShell, Add-AzAccount e Add-AzureRMAccount são aliases para Connect-AzAccount.For non-graphical PowerShell runbooks, Add-AzAccount and Add-AzureRMAccount are aliases for Connect-AzAccount. Você pode usar esses cmdlets ou pode atualizar seus módulos em sua conta de Automação para as versões mais recentes.You can use these cmdlets or you can update your modules in your Automation account to the latest versions. Talvez você precise atualizar os módulos mesmo que você tenha acabado de criar uma conta de Automação.You might need to update your modules even if you have just created a new Automation account. O uso desses cmdlets não será necessário se você estiver autenticando usando uma conta Executar como configurada com uma entidade de serviço.Use of these cmdlets 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