Aprender os principais conceitos de fluxo de trabalho do Windows PowerShell para runbooks de automatizaçãoLearning key Windows PowerShell Workflow concepts for Automation runbooks

Os Runbooks na automatizaçã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 utilizador.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 destina-se que o ajudarão a escrever runbooks com o fluxo de trabalho do PowerShell, recomendamos que escrever runbooks com o PowerShell, a menos que precisa 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. Existem várias diferenças de sintaxe durante a criação de runbooks de fluxo de trabalho do PowerShell e essas diferenças requerem um pouco mais trabalho escrever fluxos de trabalho em vigor.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 passos programados e ligados que efetuar 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. As vantagens de um fluxo de trabalho ao longo de um script normal incluem a capacidade de efetuar simultaneamente uma ação em vários dispositivos e a capacidade de 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 utiliza o Windows Workflow Foundation.A Windows PowerShell Workflow is a Windows PowerShell script that uses Windows Workflow Foundation. Enquanto o fluxo de trabalho é escrito com a sintaxe do Windows PowerShell e lançado pelo Windows PowerShell, é processada 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 neste 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

O primeiro passo para converter um script do PowerShell num fluxo de trabalho do PowerShell é colocá-lo com o fluxo de trabalho 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 o fluxo de trabalho palavra-chave seguida do corpo do script entre chavetas.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 fluxo de trabalho 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 tem de corresponder ao nome do runbook de automatização.The name of the workflow must match the name of the Automation runbook. Se o runbook está a ser importado, então o nome de ficheiro tem de corresponder ao nome de fluxo de trabalho e tem de 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, utilize o Param palavra-chave tal como faria para um script.To add parameters to the workflow, use the Param keyword just as you would to a script.

Alterações do códigoCode changes

Código de fluxo de trabalho do PowerShell parece quase idêntico ao código de script do PowerShell, com exceção de 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 fazer para um script do PowerShell para o mesmo para ser executado 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.

ActividadesActivities

Uma atividade é uma tarefa específica num fluxo de trabalho.An activity is a specific task in a workflow. Tal como um script é composto por um ou mais comandos, um fluxo de trabalho é composta por uma ou mais atividades que são executadas numa 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 em atividades quando é executada um fluxo de trabalho.Windows PowerShell Workflow automatically converts many of the Windows PowerShell cmdlets to activities when it runs a workflow. Quando especificar um destes cmdlets no 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. No caso dos cmdlets sem atividade correspondente, o fluxo de trabalho do Windows PowerShell executa automaticamente o cmdlet dentro de um InlineScript atividade.For those cmdlets without a corresponding activity, Windows PowerShell Workflow automatically runs the cmdlet within an InlineScript activity. Existe um conjunto de cmdlets que são excluídos e não pode ser utilizado num fluxo de trabalho, a menos que explicitamente incluídos num bloco 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 estes conceitos, veja utilizar atividades em fluxos de trabalho de Script.For further details on these concepts, see Using Activities in Script Workflows.

Atividades de fluxo de trabalho partilham um conjunto de parâmetros comuns para configurar o funcionamento deles.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

Não é possível 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. Isso significa que é que tem de utilizar os nomes de parâmetros.All this means is that you must use parameter names.

Por exemplo, considere o seguinte código 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 tentar executar esse código mesmo num fluxo de trabalho, receberá uma mensagem, como "conjunto de parâmetros não pode ser resolvido utilizando especificado parâmetros nomeados."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 isto, forneça o nome de parâmetro como 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 de serialização anuladosDeserialized objects

Objetos em fluxos de trabalho são anular a serialização.Objects in workflows are deserialized. Isso significa que as respetivas propriedades ainda estão disponíveis, mas não os respetivos métodos.This means that their properties are still available, but not their methods. Por exemplo, considere o seguinte código do PowerShell que pára um serviço usando o método Stop do objeto de serviço.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 tentar executá-lo num fluxo de trabalho, receberá um erro dizendo "invocação de método não é suportada num 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 estas duas linhas de código num InlineScript bloquear no qual caso $Service seria um objeto de serviço no 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 disponível.Another option is to use another cmdlet that performs the same functionality as the method, if one is available. Em nosso exemplo, o cmdlet Stop-Service fornece a mesma funcionalidade que o método Stop e poderia usar o seguinte 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

O InlineScript atividade é útil quando tiver de executar um ou mais comandos de script do PowerShell como tradicional em vez de 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 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 indicada abaixo.InlineScript uses the following syntax shown below.

InlineScript
{
    <Script Block>
} <Common Parameters>

Pode retornar a saída de um InlineScript ao atribuir 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, devolve 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
}

Pode passar valores para um bloco InlineScript, mas tem de utilizar $Using modificador do âmbito.You can pass values into an InlineScript block, but you must use $Using scope modifier. O exemplo seguinte é idêntico do 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 fundamentais em determinados fluxos de trabalho, que não suportam construções de fluxo de trabalho e só devem ser utilizadas 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 do bloco InlineScript.You cannot use checkpoints inside an InlineScript block. Se ocorrer uma falha no bloco, é necessário recomeçar 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 execução paralela dentro de um InlineScriptBlock.You cannot use parallel execution inside an InlineScriptBlock.
  • InlineScript afeta a escalabilidade do fluxo de trabalho, uma vez que realiza a sessão do Windows PowerShell durante todo o 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 como utilizar o InlineScript, consulte executar comandos do Windows PowerShell num 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 das vantagens de fluxos de trabalho do Windows PowerShell é a capacidade de executar um conjunto de comandos em paralelo em vez de sequencialmente como acontece 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.

Pode utilizar o paralela palavra-chave para criar um bloco de scripts com vários comandos executados simultaneamente.You can use the Parallel keyword to create a script block with multiple commands that run concurrently. Esta opção utiliza a seguinte sintaxe indicada abaixo.This uses the following syntax shown below. Neste caso, Activity1 e Activity2 inicia-se ao mesmo tempo.In this case, Activity1 and Activity2 starts at the same time. Activity3 começa apenas depois de Activity1 e Activity2 forem concluídos.Activity3 starts only after both Activity1 and Activity2 have completed.

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

Por exemplo, considere os seguintes comandos do PowerShell que a cópia de 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 arquivo tem de concluir a cópia antes da próxima é 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 seguinte fluxo de trabalho executa esses mesmos comandos em paralelo, para que todos eles começaram a copiar ao mesmo tempo.The following workflow runs these same commands in parallel so that they all start copying at the same time. Apenas depois de serem todos copiados é conclusão apresentada a mensagem.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 o ForEach-Parallel construção para processar comandos para cada item na 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 script são executados sequencialmente.The items in the collection are processed in parallel while the commands in the script block run sequentially. Esta opção utiliza a seguinte sintaxe indicada abaixo.This uses the following syntax shown below. Neste caso, Activity1 inicia-se ao mesmo tempo 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, Activity2 começa depois de activity1 ter sido concluído.For each item, Activity2 starts after Activity1 is complete. Activity3 começa apenas depois de Activity1 e Activity2 concluiu 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. Demasiado elevado um ThrottleLimit pode causar problemas.Too high of a ThrottleLimit can cause problems. O valor ideal para o ThrottleLimit parâmetro depende de vários fatores no seu ambiente.The ideal value for the ThrottleLimit parameter depends on many factors in your environment. Deve começar com um valor baixo de experimentar e tente aumentar os valores diferentes até encontrar uma que funcione para suas circunstâncias específicas.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 seguinte é semelhante ao exemplo anterior, copiar os ficheiros em paralelo.The following example is similar to the previous example copying files in parallel. Neste caso, é apresentada uma mensagem para cada ficheiro após copia.In this case, a message is displayed for each file after it copies. Apenas depois de serem todos copiados completamente é conclusão final apresentada a mensagem.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."
}

Nota

Não recomendamos a execução de runbooks subordinados em paralelo, uma vez que isso tenha sido mostrado 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 runbook subordinado, às vezes, não é exibido e as definições no runbook subordinado de um podem afetar outros runbooks subordinados paralela.The output from the child runbook sometimes does not show up, and settings in one child runbook can affect the other parallel child runbooks. As variáveis como $VerbosePreference, $WarningPreference e outros não podem ser propagadas para os runbooks subordinados.Variables such as $VerbosePreference, $WarningPreference, and others may not be propagated to the child runbooks. E se o runbook subordinado alterar estes valores, eles poderão não ser corretamente restaurados depois de invocação.And if the child runbook changes these values, they may not be properly restored after invocation.

Pontos de verificaçãoCheckpoints

R ponto de verificação é um instantâneo do estado atual do fluxo de trabalho que inclui o valor atual para variáveis e qualquer resultado gerado até esse 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 termina dentro de erro ou está suspenso, em seguida, na próxima vez que for executada iniciará do último ponto de verificação, em vez do 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. Pode definir um ponto de verificação num fluxo de trabalho com o Checkpoint-Workflow atividade.You can set a checkpoint in a workflow with the Checkpoint-Workflow activity. A automatização do Azure tem um recurso chamado justa, onde qualquer runbook que seja executada durante 3 horas é descarregado para permitir a execução de outros runbooks.Azure Automation has a feature called fair share, where any runbook that runs for 3 hours is unloaded to allow other runbooks to run. Finalmente, o runbook descarregado irá ser recarregado e quando é, retomará a execução do último ponto de verificação decorrido 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, eventualmente, será concluído, tem de adicionar pontos de verificação em intervalos que são executadas durante 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 é adicionado um novo ponto de verificação e, se o runbook obtém expulso depois de 3 horas devido a um erro, em seguida, o runbook vai 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 ocorrer após Activity2 causando o fluxo de trabalho terminar.In the following sample code, an exception occurs after Activity2 causing the workflow to end. Quando o fluxo de trabalho é executado novamente, começa por executar Activity2 porque foi apenas depois de definir o último ponto de verificação.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>

Deve definir pontos de verificação num fluxo de trabalho depois de atividades que poderão estar expostos a exceção e não devem ser repetem se o fluxo de trabalho é 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 seu fluxo de trabalho pode criar uma máquina virtual.For example, your workflow may create a virtual machine. Poderia definir um ponto de verificação antes e depois os 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, em seguida, os comandos seriam ser repetidos se o fluxo de trabalho é 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 for concluída com êxito, em seguida, a máquina virtual não será criada novamente quando o fluxo de trabalho é 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 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 de rede for perdida, em seguida, o fluxo de trabalho termina em erro.If the network location is lost, then the workflow ends in error. Quando é iniciada novamente, ele será retomada no último ponto de verificação que significa que apenas os ficheiros que já tenham sido copiados sã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."
}

Uma vez que as credenciais de nome de utilizador não são mantidas depois de chamar o Suspend-Workflow atividade ou após o último ponto de verificação, tem de definir as credenciais para nulo e, em seguida, recuperá-los novamente a partir do arquivo de recurso após Suspend-Workflow ou ponto de verificação é 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, poderá receber a seguinte mensagem de erro: Não é possível retomar a tarefa de fluxo de trabalho, seja porque os dados de persistência não foi possível ser guardados completamente ou guardar dados de persistência está danificada. Tem de 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 seguinte demonstra como lidar com isso em seus runbooks de 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

Add-AzureRmAccount agora é um alias para Connect-AzureRMAccount.Add-AzureRmAccount is now an alias for Connect-AzureRMAccount. Quando pesquisar a sua biblioteca de itens, se não vir Connect-AzureRMAccount, pode utilizar Add-AzureRmAccount, ou pode atualizar os módulos na conta de automatizaçã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.

Isto não é necessário se está a autenticar com uma conta Run As configuradas com um principal de serviço.This is not required if you are authenticating using a Run As account configured with a service principal.

Para obter mais informações sobre pontos de verificação, consulte adicionar pontos de verificação para um fluxo de trabalho de Script.For more information about checkpoints, see Adding Checkpoints to a Script Workflow.

Passos SeguintesNext steps