Mensagens e saída de runbook

 

Publicado: março de 2016

Aplica-se a: Windows Azure Pack for Windows Server, System Center 2012 R2 Orchestrator

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 diferentemente com cada um desses fluxos, e você deve seguir as práticas recomendadas de como usar cada um deles quando estiver criando 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.

Fluxo	Descrição	Publicado	Teste
Saída	Objetos destinados a serem consumidos por outros runbooks.	Gravado no histórico do trabalho.	Exibido no Painel de saída do teste.
Aviso	Mensagem de aviso destinada ao usuário.	Gravado no histórico do trabalho.	Exibido no Painel de saída do teste.
Erro	Mensagem de erro destinada ao usuário. Ao contrário do que ocorre com 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.	São gravadas no histórico de 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	Registros gerados automaticamente 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.	São gravados no histórico de trabalho somente se o log de andamento está ativado para o runbook.	Não são exibidos no painel de saída do teste.
Depurar	Mensagens destinadas a um usuário interativo. Não devem ser usadas em runbooks.	Não são gravadas no histórico do trabalho.	Não são gravadas 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. Em Automação, esse fluxo é usado principalmente para objetos destinados a serem consumidos por runbooks pais que chamam o runbook atual. Quando você chamar um runbook embutido por meio de um runbook pai, ele retornará dados de fluxo de saída para o esse runbook pai. Você só deve usar o fluxo de saída para comunicar informações gerais de volta para o usuário se você souber com certeza que o runbook nunca será chamado por outro runbook. Como prática recomendada, no entanto, você normalmente deve 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 a por meio de uma função

Quando você grava para o fluxo de saída em uma função que está incluída no seu runbook, a saída é passada de volta para o runbook. Se o runbook atribui essa saída a uma variável, ela não será gravada no fluxo de saída. Gravar de dentro da função em quaisquer outros fluxos gravará o fluxo correspondente para o runbook.

Considere o exemplo de runbook 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 seria:

Output outside of function

O fluxo detalhado para o trabalho de runbook seria:

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 tempo de execução, mas ele fornece uma indicação para o autor do runbook no momento de criação da saída esperada do runbook. Conforme o conjunto de ferramentas para runbooks continua a evoluir, aumenta a importância da declaração de tipos de dados de saída no momento da criação. Como resultado, é uma prática recomendada incluir essa declaração em quaisquer runbooks criados 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 gera como saída uma matriz de um determinado tipo, você ainda assim deve especificar o tipo, e não 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, fluxos de mensagens são destinados para comunicação de informações ao usuário. Há vários fluxos de mensagens para diferentes tipos de informações, e cada um é tratado diferentemente pelo Automação.

Fluxos de Advertência e Erro

Os fluxos de Advertência e Erro são destinados ao registro de problemas que ocorrem em um runbook. Eles são gravados no histórico de trabalho quando um runbook é executado, e são incluídos no painel de saída do teste no Portal de gerenciamento quando um runbook é testado. Por padrão, o runbook continuará a ser executado após uma advertência ou erro. Você pode especificar que o runbook deve ser suspenso em caso de advertência 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 ocorreria em caso de uma exceção, defina $ErrorActionPreference como Stop.

Crie um aviso ou uma mensagem de erro usando o cmdlet Write-Warning ou Write-Error. As atividades também podem gravar 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 mensagem detalhado é para informações gerais sobre a operação de runbook. Como o Fluxo de Depuração não está disponível em um runbook, as mensagens detalhadas devem ser usadas para obter informações sobre resolução de problemas. Por padrão, mensagens detalhadas de runbooks publicados não serão armazenadas no histórico de trabalho. 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 gravar em log registros detalhados para um runbook por motivos de desempenho. Ative essa opção apenas para solucionar problemas em um runbook ou depurá-lo.

A variável $VerbosePreference fica por padrão com um valor de SilentlyContinue. Não é necessário alterar essa variável em um runbook publicado para que mensagens detalhadas sejam armazenadas. Se esse valor está definido explicitamente como SilentlyContinue em um runbook publicado, então as mensagens detalhadas não são armazenadas mesmo se o runbook estiver configurado para gravar registros detalhados em log.

Ao testar um runbook, mensagens detalhadas não são exibidas, mesmo se o runbook estiver configurado para gravar registros detalhados em log. Para exibir mensagens detalhadas ao testar um runbook, você deve definir a variável $VerbosePreference com o valor Continue. Com essa variável configurada, as mensagens detalhadas serão exibidas no Painel de saída de teste do Portal de gerenciamento.

Crie 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 é destinado ao uso com um usuário interativo e não deve ser usado em runbooks.

Registros de progresso

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ê deve manter a configuração padrão de não gravar registros de andamento em log para um runbook, para assim maximizar o desempenho. Ative essa opção apenas para solucionar problemas em um runbook ou depurá-lo. Ao testar um runbook, mensagens de progresso não serão exibidas, mesmo se o runbook estiver configurado para gravar em log os registros de progresso.

O cmdlet Write-Progress não é válido em um runbook, uma vez que ele é destinado a 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 a diferentes fluxos de saída. Você pode definir essas variáveis em um runbook para controlar como ele responde aos dados enviados para 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. Observe que 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 no Windows PowerShell fora do Service Management Automation.

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 que são válidas em runbooks.

Valor	Comportamento
Continue	Registra a mensagem e continua executando o runbook.
SilentlyContinue	Continua executando o runbook sem registrar a mensagem. Isso tem o efeito de ignorar a mensagem.
Stop	Registra 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 Fluxo de saída, além de informações gerais sobre o trabalho e quaisquer eventuais exceções que tenham ocorrido. O Histórico conterá mensagens do fluxo de saída e Fluxos de Advertência e Erro, além do Fluxo detalhado e Registros de progresso se o runbook estiver configurado para o log detalhado e dos registros 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 Stream, em que você pode especificar para qual fluxo retornar. Você pode especificar Any para retornar todos os fluxos para o trabalho.

O exemplo a seguir inicia um exemplo de runbook e aguarda sua conclusão. Depois de concluído, o fluxo de saída é 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

Consulte também

Estendendo o Service Management Automation com runbooks
Runbook Authoring