Configurar saída de runbook e fluxos de mensagens

A maioria dos runbooks da Automação do Azure tem alguma forma de saída. Essa saída pode ser uma mensagem de erro para o usuário ou um objeto complexo destinado a ser usado com outro runbook. O Windows PowerShell fornece vários fluxos para enviar a saída de um script ou fluxo de trabalho. A Automação do Azure funciona com cada um desses fluxos de forma diferente. Você deve seguir as práticas recomendadas para usar os fluxos ao criar um runbook.

A tabela a seguir descreve brevemente cada fluxo com seu comportamento no portal do Azure para runbooks publicados e durante o teste de um runbook. O fluxo de saída é o fluxo principal usado para comunicação entre runbooks. Os outros fluxos são classificados como fluxos de mensagens, destinados a comunicar informações ao usuário.

Usar o fluxo de saída

O fluxo de saída é usado para a saída de objetos criados por um script ou fluxo de trabalho quando ele é executado corretamente. A Automação do Azure usa principalmente esse fluxo para objetos a serem consumidos por runbooks pai que chamam o runbook atual. Quando um pai chama um runbook embutido, o filho retorna dados do fluxo de saída para o pai.

Seu runbook usa o fluxo de saída para comunicar informações gerais ao cliente somente se ele nunca for chamado por outro runbook. Como prática recomendada, no entanto, seus runbooks normalmente devem usar o fluxo detalhado para comunicar informações gerais ao usuário.

Faça com que seu runbook grave dados no fluxo de saída usando Write-Output. Como alternativa, você pode colocar o objeto em sua própria linha no script.

#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object

Manipular a saída de uma função

Quando uma função runbook grava no fluxo de saída, a saída é passada de volta para o runbook. Se o runbook atribuir essa saída a uma variável, a saída não será gravada no fluxo de saída. Gravar em quaisquer outros fluxos de dentro da função grava no fluxo correspondente para o runbook. Considere o seguinte exemplo de runbook do Fluxo de Trabalho do PowerShell.

Workflow Test-Runbook
{
  Write-Verbose "Verbose outside of function" -Verbose
  Write-Output "Output outside of function"
  $functionOutput = Test-Function
  $functionOutput

  Function Test-Function
  {
    Write-Verbose "Verbose inside of function" -Verbose
    Write-Output "Output inside of function"
  }
}

O fluxo de saída para o trabalho de runbook é:

Output inside of function
Output outside of function

O fluxo detalhado para o trabalho de runbook é:

Verbose outside of function
Verbose inside of function

Depois de publicar o runbook e antes de iniciá-lo, você também deve ativar o registro detalhado nas configurações do runbook para obter a saída de fluxo detalhado.

Declarar tipo de dados de saída

Seguem-se exemplos de tipos de dados de saída:

• System.String
• System.Int32
• System.Collections.Hashtable
• Microsoft.Azure.Commands.Compute.Models.PSVirtualMachine

Declarar o tipo de dados de saída em um fluxo de trabalho

Um fluxo de trabalho especifica o tipo de dados de sua saída usando o atributo OutputType. Esse atributo não tem efeito durante o tempo de execução, mas fornece uma indicação em tempo de design da saída esperada do runbook. À medida que o conjunto de ferramentas para runbooks continua a evoluir, a importância de declarar tipos de dados de saída em tempo de design aumenta. Portanto, é uma prática recomendada incluir essa declaração em todos os runbooks que você criar.

O runbook de exemplo a seguir gera uma saída de um objeto string e inclui uma declaração de seu tipo de saída. Se o runbook gerar uma matriz de um determinado tipo, você ainda deverá especificar o tipo em vez de uma matriz do tipo.

Workflow Test-Runbook
{
  [OutputType([string])]

  $output = "This is some string output."
  Write-Output $output
}

Declarar o tipo de dados de saída em um runbook gráfico

Para declarar um tipo de saída em um runbook gráfico ou gráfico do Fluxo de Trabalho do PowerShell, você pode selecionar a opção de menu Entrada e Saída e inserir o tipo de saída. É recomendável usar o nome completo da classe .NET para tornar o tipo facilmente identificável quando um runbook pai fizer referência a ele. O uso do nome completo expõe todas as propriedades da classe ao barramento de dados no runbook e aumenta a flexibilidade quando as propriedades são usadas para lógica condicional, registro em log e referência como valores para outras atividades do runbook.

O exemplo a seguir mostra dois runbooks gráficos para demonstrar o recurso Input e Output. Aplicando o modelo de design de runbook modular, você tem um runbook como o modelo Authenticate Runbook gerenciando a autenticação com o Azure usando identidades gerenciadas. O segundo runbook, que normalmente executa a lógica central para automatizar um determinado cenário, neste caso executa o modelo Authenticate Runbook. Ele exibe os resultados no painel de saída Teste. Em circunstâncias normais, você faria com que esse runbook fizesse algo contra um recurso aproveitando a saída do runbook filho.

Aqui está a lógica básica do runbook AuthenticateTo-Azure .
.

O runbook inclui o tipo Microsoft.Azure.Commands.Profile.Models.PSAzureProfilede saída , que retorna as propriedades do perfil de autenticação.

Embora este runbook seja simples, há um item de configuração para chamar aqui. A última atividade executa o Write-Output cmdlet para gravar dados de perfil em uma variável usando uma expressão do PowerShell para o Inputobject parâmetro. Este parâmetro é necessário para Write-Output.

O segundo runbook neste exemplo, chamado Test-ChildOutputType, simplesmente define duas atividades.

A primeira atividade chama o runbook AuthenticateTo-Azure . A segunda atividade executa o cmdlet com a Write-Verbose Fonte de dados definida como Saída da atividade. Além disso, o caminho do campo é definido como Context.Subscription.Name, a saída de contexto do runbook AuthenticateTo-Azure .

A saída resultante é o nome da assinatura.

Trabalhar com fluxos de mensagens

Ao contrário do fluxo de saída, os fluxos de mensagens comunicam informações ao usuário. Há vários fluxos de mensagens para diferentes tipos de informações, e a Automação do Azure lida com cada fluxo de forma diferente.

Gravar saída em fluxos de aviso e erro

O aviso e o erro transmitem problemas de log que ocorrem em um runbook. A Automação do Azure grava esses fluxos no histórico de trabalhos ao executar um runbook. A automação inclui os fluxos no painel de saída de teste no portal do Azure quando um runbook é testado.

Por padrão, um runbook continua a ser executado após um aviso ou erro. Você pode especificar que seu runbook deve ser suspenso em caso de aviso ou erro fazendo com que o runbook defina uma variável de preferência antes de criar a mensagem. Por exemplo, para fazer com que o runbook seja suspenso em um erro como em uma exceção, defina a ErrorActionPreference variável como Stop.

Crie um aviso ou mensagem de erro usando o cmdlet Write-Warning ou Write-Error . As atividades também podem gravar nos fluxos de aviso e erro.

#The following lines create a warning message and then an error message that will suspend the runbook.

$ErrorActionPreference = "Stop"
Write-Warning -Message "This is a warning message."
Write-Error -Message "This is an error message that will stop the runbook because of the preference variable."

Gravar saída para depurar fluxo

A Automação do Azure usa o fluxo de mensagens de depuração para usuários interativos. Por padrão, a Automação do Azure não captura nenhum dado de fluxo de depuração, apenas dados de saída, erro e aviso são capturados, bem como dados detalhados se o runbook estiver configurado para capturá-los.

Para capturar dados de fluxo de depuração, você precisa executar duas ações em seus runbooks:

1. Defina a variável $GLOBAL:DebugPreference="Continue", que informa ao PowerShell para continuar sempre que uma mensagem de depuração for encontrada. A parte $GLOBAL: diz ao PowerShell para fazer isso no escopo global em vez de qualquer escopo local em que o script esteja no momento em que a instrução é executada.

2. Redirecionar o fluxo de depuração que não capturamos para um fluxo que capturamos, como a saída. Isso é feito definindo o redirecionamento do PowerShell em relação à instrução a ser executada. Para obter mais informações sobre o redirecionamento do PowerShell, consulte Sobre o redirecionamento .

Exemplos

Neste exemplo, o runbook é configurado usando os Write-Output cmdlets e Write-Debug com a intenção de enviar dois fluxos diferentes.

Write-Output "This is an output message." 
Write-Debug "This is a debug message."

Se esse runbook fosse executado como está, o painel de saída para o trabalho de runbook transmitiria a seguinte saída:

This is an output message.

Neste exemplo, o runbook é configurado de forma semelhante ao exemplo anterior, exceto que a instrução $GLOBAL:DebugPreference="Continue" é incluída com a adição de 5>&1 no final da Write-Debug instrução.

Write-Output "This is an output message." 
$GLOBAL:DebugPreference="Continue" 
Write-Debug "This is a debug message." 5>&1

Se esse runbook fosse executado, o painel de saída para o trabalho de runbook transmitiria a seguinte saída:

This is an output message.
This is a debug message.

Isso ocorre porque a $GLOBAL:DebugPreference="Continue" instrução diz ao PowerShell para exibir mensagens de depuração e a adição de 5>&1 ao final da Write-Debug instrução diz ao PowerShell para redirecionar o fluxo 5 (depuração) para o fluxo 1 (saída).

Gravar saída em fluxo detalhado

O fluxo de mensagens detalhado suporta informações gerais sobre a operação do runbook. Como o fluxo de depuração não está disponível para um runbook, seu runbook deve usar mensagens detalhadas para informações de depuração.

Por padrão, o histórico de trabalhos não armazena mensagens detalhadas de runbooks publicados, por motivos de desempenho. Para armazenar mensagens detalhadas, use a guia Configurar do portal do Azure com a configuração Registrar registros detalhados para configurar seus runbooks publicados para registrar mensagens detalhadas. Ative essa opção apenas para solucionar problemas ou depurar um runbook. Na maioria dos casos, você deve manter a configuração padrão de não registrar registros detalhados.

Ao testar um runbook, mensagens detalhadas não são exibidas, mesmo que o runbook esteja configurado para registrar registros detalhados. Para exibir mensagens detalhadas durante o teste de um runbook, você deve definir a VerbosePreference variável como Continue. Com esse conjunto de variáveis, mensagens detalhadas são exibidas no painel de saída de teste do portal do Azure.

O código a seguir cria uma mensagem detalhada usando o cmdlet Write-Verbose .

#The following line creates a verbose message.

Write-Verbose -Message "This is a verbose message."

Lidar com registros de progresso

Você pode usar a guia Configurar do portal do Azure para configurar um runbook para registrar registros de progresso. A configuração padrão é não registrar os registros, para maximizar o desempenho. Na maioria dos casos, você deve manter a configuração padrão. Ative essa opção apenas para solucionar problemas ou depurar um runbook.

Se você habilitar o registro de registro de progresso, seu runbook gravará um registro no histórico de trabalhos antes e depois de cada execução de atividade. O teste de um runbook não exibe mensagens de progresso, mesmo que o runbook esteja configurado para registrar registros de progresso.

Trabalhar com variáveis de preferência

Você pode definir determinadas variáveis de preferência do Windows PowerShell em seus runbooks para controlar a resposta aos dados enviados para diferentes fluxos de saída. A tabela a seguir lista as variáveis de preferência que podem ser usadas em runbooks, com seus valores padrão e válidos. Valores adicionais estão disponíveis para as variáveis de preferência quando usados no Windows PowerShell fora da Automação do Azure.

A tabela a seguir lista o comportamento para os valores de variáveis de preferência que são válidos em runbooks.

Obter resultados e mensagens do runbook

Recuperar saída de runbook e mensagens no portal do Azure

Você pode exibir os detalhes de um trabalho de runbook no portal do Azure usando a guia Trabalhos para o runbook. O resumo do trabalho exibe os parâmetros de entrada e o fluxo de saída, além de informações gerais sobre o trabalho e quaisquer exceções que ocorreram. O histórico de trabalhos inclui mensagens do fluxo de saída e fluxos de aviso e erro. Ele também inclui mensagens do fluxo detalhado e registros de progresso se o runbook estiver configurado para registrar registros detalhados e de progresso.

Recuperar saída de runbook e mensagens no Windows PowerShell

No Windows PowerShell, você pode recuperar a saída e as mensagens de um runbook usando o cmdlet Get-AzAutomationJobOutput . Esse cmdlet requer a ID do trabalho e tem um parâmetro chamado Stream para especificar o fluxo a ser recuperado. Você pode especificar um valor de Any para esse parâmetro para recuperar todos os fluxos para o trabalho.

O exemplo a seguir inicia um runbook de exemplo e aguarda sua conclusão. Quando o runbook conclui a execução, o script coleta o fluxo de saída do runbook do trabalho.

$job = Start-AzAutomationRunbook -ResourceGroupName "ResourceGroup01" `
  -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook"

$doLoop = $true
While ($doLoop) {
  $job = Get-AzAutomationJob -ResourceGroupName "ResourceGroup01" `
    -AutomationAccountName "MyAutomationAccount" -Id $job.JobId
  $status = $job.Status
  $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
}

Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
  -AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Output

# For more detailed job output, pipe the output of Get-AzAutomationJobOutput to Get-AzAutomationJobOutputRecord
Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
  -AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Any | Get-AzAutomationJobOutputRecord

Recuperar saída de runbook e mensagens em runbooks gráficos

Para runbooks gráficos, o registro extra de saída e mensagens está disponível na forma de rastreamento no nível da atividade. Existem dois níveis de rastreamento: Básico e Detalhado. O rastreamento básico exibe a hora de início e término de cada atividade no runbook, além de informações relacionadas a quaisquer tentativas de atividade. Alguns exemplos são o número de tentativas e a hora de início da atividade. O rastreamento detalhado inclui recursos básicos de rastreamento, além de registro de dados de entrada e saída para cada atividade.

Atualmente, o rastreamento no nível da atividade grava registros usando o fluxo detalhado. Portanto, você deve habilitar o log detalhado ao habilitar o rastreamento. Para runbooks gráficos com rastreamento habilitado, não há necessidade de registrar registros de progresso. O rastreio básico serve o mesmo propósito e é mais informativo.

Você pode ver na imagem que habilitar o registro detalhado e o rastreamento para runbooks gráficos torna muito mais informações disponíveis na visualização Job Streams de produção. Essas informações extras podem ser essenciais para solucionar problemas de produção com um runbook.

No entanto, a menos que você precise dessas informações para acompanhar o progresso de um runbook para solução de problemas, convém manter o rastreamento desativado como uma prática geral. Os registros de rastreamento podem ser especialmente numerosos. Com o rastreamento de runbook gráfico, você pode obter de dois a quatro registros por atividade, dependendo da sua configuração de rastreamento Básico ou Detalhado.

Para habilitar o rastreamento no nível da atividade:

1. No portal do Azure, abra a sua conta da Automatização.

2. Selecione Runbooks em Process Automation para abrir a lista de runbooks.

3. Na página Runbooks, selecione um runbook gráfico na sua lista de runbooks.

4. Em Configurações, clique em Registro e rastreamento.

5. Na página Registo e Rastreio, em Registar registos detalhados, clique em Ativado para ativar o registo detalhado.

6. Em Rastreamento no nível de atividade, altere o nível de rastreamento para Básico ou Detalhado, com base no nível de rastreamento necessário.
   

   

Recuperar saída de runbook e mensagens em logs do Microsoft Azure Monitor

A Automação do Azure pode enviar o status do trabalho runbook e fluxos de trabalho para seu espaço de trabalho do Log Analytics. O Azure Monitor dá suporte a logs que permitem:

• Obter informações sobre as suas tarefas de Automatização.
• Acione um e-mail ou alerta com base no status do seu trabalho de runbook, por exemplo, Falha ou Suspenso.
• Escreva consultas avançadas em fluxos de trabalho.
• Correlacionar tarefas em contas de Automatização.
• Visualize o histórico do trabalho.

Para obter mais informações sobre como configurar a integração com os Logs do Azure Monitor para coletar, correlacionar e agir sobre dados de trabalho, consulte Encaminhar status e fluxos de trabalho da Automação para os Logs do Azure Monitor.

Próximos passos

• Para consultas de exemplo, consulte Consultas de exemplo para logs de trabalho e fluxos de trabalho
• Para trabalhar com runbooks, consulte Gerenciar runbooks na Automação do Azure.
• Se você não estiver familiarizado com scripts do PowerShell, consulte a documentação do PowerShell .
• Para obter a referência do cmdlet do PowerShell de Automação do Azure, consulte Az.Automation.