Saída de runbook e mensagens

Importante

Esta versão do SMA (Service Management Automation) chegou ao fim do suporte. Recomendamos que você atualize para o SMA 2022.

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. A Automação de Gerenciamento de Serviços funciona com cada um desses fluxos de maneira diferente e você deve seguir as práticas recomendadas de como 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.	Exibido no painel de saída do teste somente se $VerbosePreference for definido como Continuar no runbook.
Andamento	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 são destinados 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 retorna dados de 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. Há 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 deve ser suspenso em um aviso ou erro, definindo uma variável de preferência no runbook antes de criar a mensagem. Por exemplo, para fazer com que um runbook seja suspenso em caso de erro como se fosse uma exceção, defina $ErrorActionPreference como Parar.

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 Stream de Depuração não está disponível em um runbook, mensagens detalhadas devem ser usadas para solucionar problemas de informações. 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 se o runbook estiver 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 mensagens detalhadas ao testar um runbook, você deve definir a variável $VerbosePreference como Continuar. 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 se o runbook estiver configurado para registrar registros de progresso.

O cmdlet Write-Progress não é válido em um runbook, pois destina-se 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 usados em Windows PowerShell fora da Automação de Gerenciamento de Serviços.

Variável	Valor Padrão	Valores válidos
WarningPreference	Continue	Stop Continue SilentlyContinue
ErrorActionPreference	Continue	Stop Continue SilentlyContinue
VerbosePreference	SilentlyContinue	Stop Continue SilentlyContinue

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

Valor	Comportamento
Continue	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 Stream de Saída, além de informações gerais sobre o trabalho e quaisquer exceções se eles ocorreram. O Histórico incluirá mensagens do Stream de Saída e fluxos de aviso e de erro, além do Stream detalhado e registros de progresso se o runbook estiver configurado para registrar registros detalhados e de progresso.

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 Fluxo onde você pode especificar qual fluxo retornar. Você pode especificar Qualquer para retornar todos os fluxos de 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

Criar runbooks de automação.