Saída de runbook e mensagens

A maioria dos runbooks de automação terá alguma forma de saída, como uma mensagem de erro para o usuário ou um objeto complexo destinado a ser consumido por outro fluxo de trabalho. O Windows PowerShell fornece múltiplos fluxos para enviar a saída por meio de um fluxo de trabalho. O Service Management Automation funciona com cada um desses fluxos de maneira diferente e você deve seguir as práticas recomendadas para usar cada um ao criar um runbook.

A tabela a seguir oferece uma breve descrição de cada um dos fluxos e de seus comportamentos no Portal de gerenciamento, tanto ao executar um runbook publicado quanto ao testar um runbook. Mais detalhes sobre cada fluxo são fornecidos nas seções subsequentes.

Stream	Descrição	Publicado	Teste
Saída	Objetos que se destinam a consumo de outros runbooks.	Gravado no histórico do trabalho.	Exibido no Painel de Saída do Teste.
Aviso	Mensagem de aviso para o usuário.	Gravado no histórico do trabalho.	Exibido no Painel de Saída do Teste.
Erro	Mensagem de erro para o usuário. Ao contrário de uma exceção, o runbook continua após uma mensagem de erro por padrão.	Gravado no histórico do trabalho.	Exibido no Painel de Saída do Teste.
Detalhado	Mensagens fornecendo informações gerais ou referentes a solução de problemas.	Gravado no histórico do trabalho somente se o log detalhado estiver ativado para o runbook.	São exibidas no painel Saída de teste somente se $VerbosePreference estiver definido como Continue no runbook.
Progresso	Os registros são automaticamente gerados antes e depois de cada atividade no runbook. O runbook não deve tentar criar seus próprios registros de progresso, pois eles se destinam a um usuário interativo.	Gravado no histórico do trabalho somente se o log de andamento estiver ativado para o runbook.	Não exibido no Painel Saída de Teste.
Depurar	As mensagens destinadas a um usuário interativo. Não deve ser usado em runbooks.	Não gravado no histórico do trabalho.	Não gravado no Painel Saída de Teste.

Fluxo de saída

O fluxo de saída é destinado à saída de objetos criados por um fluxo de trabalho quando ele é executado corretamente. Na Automação, esse fluxo é usado principalmente para objetos destinados a serem consumidos por runbooks pai que chamam o runbook atual. Quando você chamar um runbook embutido de um runbook pai, ele retornará dados do fluxo de saída para o pai. Você só deverá usar o fluxo de saída para comunicar informações gerais para o usuário se souber que o runbook nunca será chamado por outro runbook. Como prática recomendada, no entanto, você normalmente deverá usar o Fluxo Detalhado para comunicar informações gerais para o usuário.

Você pode gravar dados no fluxo de saída usando Write-Output ou colocando o objeto em sua própria linha no runbook.

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

Saída de uma função

Quando você grava o fluxo de saída em uma função incluída no seu runbook, a saída é passada de volta ao runbook. Se o runbook atribuir essa saída a uma variável, ela não será gravada no fluxo de saída. A gravação de qualquer outro fluxo de dentro de uma função gravará o fluxo correspondente no runbook.

Considere os cenários de exemplo a seguir.

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

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

O fluxo de saída para o trabalho de runbook deveria ser:

Output outside of function

O fluxo detalhado para o trabalho de runbook deveria ser:

Verbose outside of function
Verbose inside of function

A variável $functionOutput teria o valor:

Output inside of function

Declarar o tipo de dados de saída

Um fluxo de trabalho pode especificar o tipo de dados de sua saída usando o atributo OutputType. Esse atributo não tem nenhum efeito durante o runtime, mas ele fornece uma indicação para o autor do runbook no momento de criação da saída esperada do runbook. Como o conjunto de ferramentas para runbooks continua a evoluir, a importância de declarar tipos de dados de saída em tempo de design aumentará. Como resultado, é uma melhor prática incluir essa declaração em qualquer runbook criado por você.

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

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

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

Fluxos de mensagens

Ao contrário do fluxo de saída, os fluxos de mensagens destinam-se a comunicar informações ao usuário. Existem vários fluxos de mensagens para diferentes tipos de informações, e cada um é tratado de forma diferente pela Automação.

Selecione a guia necessária para saber mais sobre esses fluxos de mensagens:

Fluxos de aviso e erro

Os fluxos de Aviso e de Erro pretendem registrar problemas que ocorrem em um runbook. Eles são gravados no histórico de trabalhos quando um runbook é executado e são incluídos no Painel de Saída de Teste no Portal de Gerenciamento quando um runbook é testado. Por padrão, o runbook continuará a ser executado após um aviso ou um erro. Você pode especificar que o runbook seja suspenso em um aviso ou um erro ao definir uma variável de preferência no runbook antes de criar a mensagem. Por exemplo, para fazer com que um runbook seja suspenso em um erro como o faria em uma exceção, defina $ErrorActionPreference como Stop.

Crie uma mensagem de aviso ou de erro usando o cmdlet Write-Warning ou Write-Error. As atividades também podem ser gravadas nesses fluxos.

#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."

Fluxo detalhado

O fluxo de mensagens Detalhado destina-se a informações gerais sobre a operação do runbook. Como o Fluxo de Depuração não está disponível em um runbook, mensagens detalhadas devem ser usadas para solucionar informações de solução de problemas. Por padrão, as mensagens detalhadas de runbooks publicados não serão armazenadas no histórico de trabalhos. Para armazenar mensagens detalhadas, configurar runbooks publicados nos Registros detalhados de log , na guia Configurar do runbook no Portal de gerenciamento. Na maioria dos casos, você deve manter a configuração padrão de não obter o log de registros detalhados para um runbook por motivos de desempenho. Só ative essa opção para solucionar problemas ou depurar um runbook.

A variável $VerbosePreference fica por padrão com um valor de SilentlyContinue. Você não precisa alterar essa variável em um runbook publicado para que mensagens detalhadas sejam armazenadas. No entanto, se esse valor for definido explicitamente como SilentlyContinue em um runbook publicado, as mensagens detalhadas não serão armazenadas, mesmo que o runbook esteja configurado para registrar registros detalhados.

Quando testar um runbook, as mensagens detalhadas não serão exibidas mesmo que o runbook esteja configurado para registros detalhados de log. Para exibir as mensagens detalhadas enquanto testa um runbook, você deverá definir a variável $VerbosePreference como Continue. Com essa variável configurada, as mensagens detalhadas serão exibidas no Painel de saída de teste do Portal de gerenciamento.

Criar uma mensagem detalhada usando o cmdlet Write-Verbose .

#The following line creates a verbose message.

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

Fluxo de depuração

O fluxo de depuração destina-se ao uso com um usuário interativo e não deve ser usado em runbooks.

Registros de andamento

Se você configurar um runbook para gravar registros de progresso em log (na guia Configurar do runbook, no Portal de gerenciamento), então um registro será gravado no histórico do trabalho antes e após a execução de cada atividade. Na maioria dos casos, você deverá manter a configuração padrão de não obter o log de registros detalhados para um runbook para maximizar o desempenho. Só ative essa opção para solucionar problemas ou depurar um runbook. Ao testar um runbook, as mensagens de progresso não são exibidas, mesmo que o runbook esteja configurado para registrar registros de progresso.

O cmdlet Write-Progress não é válido em um runbook, pois se destina ao uso com um usuário interativo.

Variáveis de preferência

O Windows PowerShell usa variáveis de preferência para determinar como responder aos dados enviados para fluxos de saída diferentes. Você pode definir essas variáveis em um runbook para controlar como ele responde aos dados enviados em diferentes fluxos.

A tabela a seguir lista as variáveis de preferência que podem ser usadas em runbooks com seus valores válidos e padrão.

Observação

Essa tabela inclui somente os valores que são válidos em um runbook. Valores adicionais são válidos para as variáveis de preferência quando usadas no Windows PowerShell fora do Service Management Automation.

Variável	Valor padrão	Valores válidos
WarningPreference	Continuar	Stop Continuar<\br> \SilentlyContinue
ErrorActionPreference	Continuar	Parar Continuar SilentlyContinue
VerbosePreference	SilentlyContinue	Parar Continuar SilentlyContinue

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

Valor	Comportamento
Continuar	Registra em log a mensagem e continua executando o runbook.
SilentlyContinue	Continua executando o runbook sem registrar em log a mensagem. Isso tem o efeito de ignorar a mensagem.
Stop	Registra em log a mensagem e suspende o runbook.

Recuperando mensagens e saída de runbook

Portal de gerenciamento

Você pode exibir os detalhes de um trabalho de runbook no Portal de gerenciamento na guia Trabalhos de um runbook. O Resumo do trabalho exibirá os parâmetros de entrada e o Output Stream , além de informações gerais sobre o trabalho e quaisquer eventuais exceções que tenham ocorrido. O Histórico incluirá mensagens do Fluxo de Saída e dos Fluxos de Erro e de Aviso, além do Fluxo Detalhado e dos Registros de Andamento, caso o runbook esteja configurado para o log de registros detalhados e de andamento.

Windows PowerShell

No Windows PowerShell, você pode recuperar mensagens e a saída de um runbook usando o cmdlet Get-SmaJobOutput . Esse cmdlet requer a identificação do trabalho e tem um parâmetro chamado Stream , em que você pode especificar para qual fluxo retornar. Você pode especificar Any para retornar todos os fluxos do trabalho.

O exemplo a seguir inicia um runbook de exemplo e aguarda a sua conclusão. Depois de concluído, seu fluxo de saída será coletado do trabalho.

$webServer = 'https://MyServer'
$port = 9090
$runbookName = "Test-Runbook"
$job = Start-SmaRunbook -WebServiceEndpoint $webServer -Port $port -Name $runbookName

$doLoop = $true
While ($doLoop) {
   $job = Get-SmaJob -WebServiceEndpoint $webServer -Port $port -Id $job.Id
   $status = $job.Status
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped")
}

Get-SmaJobOutput -WebServiceEndpoint $webServer -Port $port -Id $job.Id -Stream Output

Próximas etapas

Crie runbooks de automação.