Aprenda fluxo de trabalho PowerShell para Azure AutomationLearn PowerShell Workflow for Azure Automation

Os runbooks em Azure Automation são implementados como fluxos de trabalho Windows PowerShell, scripts Windows PowerShell que utilizam a 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 passos programados e ligados que efetuam tarefas de longa execução ou requerem a coordenação de vários passos em vários dispositivos ou nós geridos.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.

Enquanto um fluxo de trabalho é escrito com a sintaxe Do Windows PowerShell e lançado pelo Windows PowerShell, é processado pela 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 sobre um script normal incluem o desempenho simultâneo de uma ação contra vários dispositivos e a recuperação automática 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.

Nota

Um script PowerShell Workflow é muito semelhante a um script Windows PowerShell, mas tem algumas diferenças significativas que podem ser confusas para um novo utilizador.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. Por isso, recomendamos que escreva os seus livros de execução utilizando o Fluxo de Trabalho PowerShell apenasse precisar de utilizar postos de controlo .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 neste artigo, consulte "Começar com o Fluxo de Trabalho do Windows PowerShell".For complete details of the topics in this article, see Getting Started with Windows PowerShell Workflow.

Use a palavra-chave do fluxo de trabalhoUse Workflow keyword

O primeiro passo para converter um script PowerShell num fluxo de trabalho PowerShell é a sua conversão com a Workflow palavra-chave.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 Workflow palavra-chave seguida pelo corpo do script incluído em aparelhos.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 Workflow palavra-chave como mostrado na seguinte sintaxe: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 livro de trabalho Automation.The name of the workflow must match the name of the Automation runbook. Se o livro de recortes estiver a ser importado, o nome do ficheiro deve 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 Param palavra-chave tal como faria num script.To add parameters to the workflow, use the Param keyword just as you would in a script.

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

O código de fluxo de trabalho PowerShell parece quase idêntico ao código de script PowerShell, exceto algumas alterações significativas.PowerShell Workflow code looks almost identical to PowerShell script code except for a few significant changes. As secções seguintes descrevem as alterações que precisa de fazer a um script PowerShell para que possa ser executada num 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 num fluxo de trabalho que é realizado numa sequência.An activity is a specific task in a workflow that is performed in a sequence. A execução de um Fluxo de Trabalho do Windows PowerShell converte automaticamente muitos dos cmdlets do Windows PowerShell em atividades.Windows PowerShell Workflow automatically converts many of the Windows PowerShell cmdlets to activities when it runs a workflow. Quando especificar um destes cmdlets no seu runbook, a atividade correspondente é gerida pela 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 tiver atividade correspondente, o fluxo de trabalho do Windows PowerShell executa automaticamente o cmdlet numa atividade InlineScript.If a cmdlet has no corresponding activity, Windows PowerShell Workflow automatically runs the cmdlet in an InlineScript activity. Alguns cmdlets estão excluídos e não podem ser utilizados num fluxo de trabalho a menos que os inclua explicitamente num bloco 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, consulte a Utilização de Atividades em Fluxos de Trabalho de Script.For more information, see Using Activities in Script Workflows.

As atividades de fluxo de trabalho partilham um conjunto de parâmetros comuns que permitem configurar o funcionamento delas.Workflow activities share a set of common parameters to configure their operation. Ver about_WorkflowCommonParameters.See about_WorkflowCommonParameters.

Parâmetros posicionaisPositional parameters

Não pode utilizar parâmetros posicionais com atividades e cmdlets num fluxo de trabalho.You can't use positional parameters with activities and cmdlets in a workflow. Portanto, deve usar nomes de parâmetros.Therefore, you must use parameter names. Considere o seguinte código que obtém todos os serviços de execução:Consider the following code that gets all running services:

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

Se tentar executar este código num fluxo de trabalho, recebe uma mensagem como Parameter set cannot be resolved using the specified named parameters. Para corrigir este 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 deserizadosDeserialized objects

Os objetos em fluxos de trabalho são desseerizados, o que significa que as suas propriedades ainda estão disponíveis, mas não os seus métodos.Objects in workflows are deserialized, meaning that their properties are still available, but not their methods. Por exemplo, considere o seguinte código PowerShell, que para um serviço utilizando o Stop método do Service objeto.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 tentar executá-lo num fluxo de trabalho, recebe um erro dizendo 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 é embrulhar estas duas linhas de código num bloco InlineScript.One option is to wrap these two lines of code in an InlineScript block. Neste 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 estiver 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 Stop-Service cmdlet fornece a mesma funcionalidade que o Stop método, e pode utilizar o seguinte código 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
}

Utilizar InlineScriptUse InlineScript

A InlineScript atividade é útil quando precisa executar um ou mais comandos como script tradicional PowerShell em vez de fluxo de trabalho 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 num fluxo de trabalho são enviados para o Windows Workflow Foundation para processamento, os comandos num bloco 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 utiliza a seguinte sintaxe mostrada abaixo.InlineScript uses the following syntax shown below.

InlineScript
{
    <Script Block>
} <Common Parameters>

Pode devolver 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, produz o nome de 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
}

Pode passar valores para um bloco InlineScript, mas tem de utilizar $Using modificador de âmbito.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 de 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 do InlineScript possam ser críticas em certos fluxos de trabalho, não suportam construções de fluxos de trabalho.While InlineScript activities might be critical in certain workflows, they do not support workflow constructs. Deve usá-las apenas quando necessário pelas seguintes razões:You should use them only when necessary for the following reasons:

  • Não é possível utilizar pontos de verificação dentro de um bloco InlineScript.You can't use checkpoints inside an InlineScript block. Se ocorrer uma falha dentro do bloco, deve ser retomado a partir do início do bloco.If a failure occurs within the block, it must resume from the beginning of the block.
  • Não é possível utilizar 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 detém a sessão Windows PowerShell durante todo o comprimento do bloco 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 a utilização do InlineScript, consulte os Comandos PowerShell do Windows em fluxo de trabalho e about_InlineScript.For more information on using InlineScript, see Running Windows PowerShell Commands in a Workflow and about_InlineScript.

Utilizar processamento paraleloUse parallel processing

Uma das vantagens dos Fluxos de Trabalho do Windows PowerShell é a capacidade de executar um conjunto de comandos paralelamente, em vez de sequencialmente como acontece com um script normal.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.

Pode utilizar a Parallel palavra-chave para criar um bloco de scripts com vários comandos que funcionam simultaneamente.You can use the Parallel keyword to create a script block with multiple commands that run concurrently. Isto utiliza a seguinte sintaxe mostrada abaixo.This uses the following syntax shown below. Neste caso, a Atividade1 e a Atividade2 começam ao mesmo tempo.In this case, Activity1 and Activity2 starts at the same time. A atividade 3 só começa depois de concluída a Atividade1 e a Atividade2.Activity3 starts only after both Activity1 and Activity2 have completed.

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

Por exemplo, considere os seguintes comandos PowerShell que copiam vários ficheiros para um destino de rede.For example, consider the following PowerShell commands that copy multiple files to a network destination. Estes comandos são executados sequencialmente para que um ficheiro termine de copiar antes do início do próximo.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 que se segue executa estes mesmos comandos em paralelo para que todos 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. Só depois de todas serem copiadas é que a mensagem de conclusão é exibida.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."
}

Pode utilizar a ForEach -Parallel construção para processar comandos para cada item numa coleção em simultâneo.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 paralelamente enquanto os comandos no bloco de scripts são executados sequencialmente.The items in the collection are processed in parallel while the commands in the script block run sequentially. Este processo utiliza a seguinte sintaxe mostrada abaixo.This process uses the following syntax shown below. Neste caso, a Activity1 começa ao mesmo tempo para todos os itens da coleção.In this case, Activity1 starts at the same time for all items in the collection. Para cada item, a Activity2 começa depois da Atividade1 estar completa.For each item, Activity2 starts after Activity1 is complete. A atividade3 só começa depois de tanto a Atividade1 como a Activity2 terem concluído para todos os itens.Activity3 starts only after both Activity1 and Activity2 have completed for all items. Usamos o ThrottleLimit parâmetro para limitar o paralelismo.We use the ThrottleLimit parameter to limit the parallelism. Um pouco alto 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 seu ambiente.The ideal value for the ThrottleLimit parameter depends on many factors in your environment. Comece com um valor baixo e tente diferentes valores de aumento 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 que copia ficheiros em paralelo.The following example is similar to the previous example copying files in parallel. Neste caso, é apresentada uma mensagem para cada ficheiro depois de cópias.In this case, a message is displayed for each file after it copies. Só depois de todas copiadas é que a mensagem final de conclusão é exibida.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."
}

Nota

Não recomendamos a execução de livros para crianças em paralelo, uma vez que este foi demonstrado para dar resultados pouco fiáveis.We do not recommend running child runbooks in parallel since this has been shown to give unreliable results. A saída do livro de crianças às vezes não aparece, e as configurações num livro de ensaios para crianças podem afetar os outros livros paralelos para crianças.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 VerbosePreference WarningPreference como, e outras, podem não se propagar aos livros infantis.Variables such as VerbosePreference, WarningPreference, and others might not propagate to the child runbooks. E se o livro de crianças alterar estes valores, estes podem não ser devidamente restaurados após a invocação.And if the child runbook changes these values, they might not be properly restored after invocation.

Utilize postos de controlo num 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 para variáveis e qualquer saída gerada até esse 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 termina por engano ou é suspenso, começa a partir do seu último ponto de verificação da próxima vez que funcionar, em vez de começar no 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.

Pode definir um ponto de verificação num fluxo de trabalho com a Checkpoint-Workflow atividade.You can set a checkpoint in a workflow with the Checkpoint-Workflow activity. A Azure Automation tem uma funcionalidade chamada fair share, para a qual qualquer livro de execução que tenha uma duração de três horas é descarregado para permitir a execução de outros 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. Eventualmente, o livro de bordo descarregado é recarregado.Eventually, the unloaded runbook is reloaded. Quando estiver, retoma a execução do último ponto de verificação tirado no livro de recortes.When it is, it resumes execution from the last checkpoint taken in the runbook.

Para garantir que o livro de bordo eventualmente se completa, deve adicionar pontos de verificação em intervalos que duram 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 for adicionado um novo ponto de verificação, e se o livro de execuções for despejado após três horas devido a um erro, o livro de recortes é 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 seguinte, ocorre uma exceção após a Atividade2, fazendo com que o fluxo de trabalho termine.In the following example, an exception occurs after Activity2, causing the workflow to end. Quando o fluxo de trabalho é executado novamente, começa por executar a Atividade2, uma vez que esta atividade foi logo após o último checkpoint 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>

Definir postos de controlo num fluxo de trabalho após atividades que possam ser propensas a exceções e não devem ser repetidos 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 seu fluxo de trabalho pode criar uma máquina virtual.For example, your workflow might create a virtual machine. 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 são repetidos se o fluxo de trabalho for reiniciado.If the creation fails, then the commands are repeated if the workflow is started again. Se o fluxo de trabalho falhar após o sucesso da criação, a máquina virtual não voltará a ser criada 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 seguinte copia vários ficheiros para uma localização de rede e define um ponto de verificação após cada ficheiro.The following example copies multiple files to a network location and sets a checkpoint after each file. Se a localização da rede for perdida, o fluxo de trabalho termina por engano.If the network location is lost, then the workflow ends in error. Quando é reinicia, retoma no último posto de controlo.When it is started again, it resumes at the last checkpoint. Apenas os ficheiros 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 de nome de utilizador não são persistidos depois de ligar para a atividade suspender o fluxo de trabalho ou após o último ponto de verificação, é necessário definir as credenciais para nulos e, em seguida, recuperá-las novamente da loja de ativos depois ou o ponto de Suspend-Workflow verificação é 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, poderá receber a seguinte mensagem de erro: 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 que se segue demonstra como lidar com esta situação nos seus livros de fluxo de trabalho 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
        }
}

Nota

Para livros de execução powershell não gráficos, Add-AzAccount e Add-AzureRMAccount são pseudónimos para Connect-AzAccount.For non-graphical PowerShell runbooks, Add-AzAccount and Add-AzureRMAccount are aliases for Connect-AzAccount. Pode utilizar estes cmdlets ou atualizar os seus módulos na sua conta Automation 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. Poderá ter de atualizar os seus módulos mesmo que tenha acabado de criar uma nova conta Automation.You might need to update your modules even if you have just created a new Automation account. A utilização destes cmdlets não é necessária se estiver a autenticar utilizando uma conta Run As configurada com um titular 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 obter mais informações sobre os pontos de verificação, consulte adicionar pontos de verificação a um fluxo de trabalho do script.For more information about checkpoints, see Adding Checkpoints to a Script Workflow.

Passos seguintesNext steps