Resultados e Mensagens do Runbook

 

Publicado: junho de 2016

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

A maior parte dos runbooks de Automatização terá alguma forma de resultado, como uma mensagem de erro para o utilizador ou um objeto complexo destinado a ser consumido por outro fluxo de trabalho. O Windows PowerShell disponibiliza vários fluxos para enviar o resultado de um fluxo de trabalho. Service Management Automation funciona com cada um destes fluxos de forma diferente e devem ser adotadas as melhores práticas para utilizar cada um deles quando cria um runbook.

A tabela seguinte apresenta uma descrição breve de cada um dos fluxos e do respetivo comportamento no Portal de Gestão, tanto ao executar um runbook publicado, como ao testar um runbook. São fornecidos detalhes adicionais sobre cada um dos fluxos nas secções subsequentes.

Fluxo	Descrição	Publicado	Teste
Resultado	Objetos destinados a ser consumidos por outros runbooks.	Escrito no histórico da tarefa.	Apresentado no Painel de Resultados do Teste.
Aviso	Mensagem de aviso para o utilizador.	Escrito no histórico da tarefa.	Apresentado no Painel de Resultados do Teste.
Erro	Mensagem de erro para o utilizador. Ao contrário de uma exceção, por predefinição, o runbook continua após uma mensagem de erro.	Escrito no histórico da tarefa.	Apresentado no Painel de Resultados do Teste.
Verboso	Mensagens que fornecem informações gerais ou de resolução de problemas.	Escrito no histórico da tarefa apenas se o registo verboso estiver ativado no runbook.	Só é apresentado no Painel de Resultados do Teste se $VerbosePreference estiver definido como Continuar no runbook.
Progresso	Registos gerados automaticamente antes e depois de cada atividade no runbook. O runbook não deve tentar criar os seus próprios registos de progresso, uma vez que estes se destinam a um utilizador interativo.	Só é escrito no histórico da tarefa se o registo de progressos estiver ativado no runbook.	Não é apresentado no Painel de Resultados do Teste.
Depurar	Mensagens destinadas a um utilizador interativo. Não devem ser utilizadas em runbooks.	Não é escrito no histórico da tarefa.	Não é escrito no Painel de Resultados do Teste.

Fluxo de Saída

O Fluxo de saída destina-se à saída de objetos criados por um fluxo de trabalho quando este é executado corretamente. No Automation, este fluxo é utilizado sobretudo para objetos que se destinam a ser consumidos por runbooks principais que chamem o runbook atual. Quando chama um runbook inline a partir de um runbook principal, são devolvidos dados do fluxo de saída ao principal. Só deve utilizar o fluxo de saída para comunicar informações gerais ao utilizador se souber que o runbook nunca irá ser chamado por outro runbook. Contudo, como melhor prática, por norma, deve utilizar o Fluxo Verboso para comunicar informações gerais ao utilizador.

Pode escrever dados no fluxo de saída através de Write-Output ou ao colocar o objeto na 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 escreve no fluxo de saída numa função que esteja incluída no runbook, a saída é reenviada para o runbook. Se o runbook atribuir essa saída a uma variável, não será escrita no fluxo de saída. Se escrever em quaisquer outros fluxos a partir da função, escreverá no fluxo correspondente do runbook.

Considere o runbook de exemplo seguinte.

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 da tarefa do runbook seria:

Output outside of function

O fluxo verboso da tarefa do runbook seria:

Verbose outside of function
Verbose inside of function

A variável $functionOutput teria o valor:

Output inside of function

Declarar os Tipo de Dados de Saída

Os fluxos de trabalho podem especificar o tipo de dados das respetivas saídas ao utilizar o atributo OutputType. Este atributo não tem efeito durante o tempo de execução, mas disponibiliza uma indicação da saída prevista do runbook ao autor do mesmo no momento da conceção. Uma vez que o conjunto de ferramentas dos runbooks continua a evoluir, a importância de declarar os tipos de dados de saída no momento da conceção será cada vez maior. Como consequência, é melhor prática incluir esta declaração em todos os runbooks que criar.

O runbook de exemplo seguinte cria uma saída de objeto de cadeia e inclui uma declaração do respetivo tipo de saída. Se o seu runbook criar uma saída de matriz de um determinado tipo, não deve deixar de especificar o tipo, por oposição 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 utilizador. Existem vários fluxos de mensagens para diferentes tipos de informações e cada um é processado de forma diferente pelo Automation.

Fluxos de Avisos e de Erros

Os Fluxos de Avisos e de Erros destinam-se a registar problemas que ocorrem num runbook. São escritos no histórico da tarefa quando um runbook é executado e incluídos no Painel de Resultados do Teste, no Portal de Gestão, quando esse runbook é testado. Por predefinição, o runbook continuará a ser executado após um aviso ou um erro. É possível especificar que um runbook deve ser suspenso após um aviso ou um erro, ao definir uma variável de preferência no runbook antes de criar a mensagem. Por exemplo, para que um runbook seja suspenso após um erro, como aconteceria após uma exceção, defina $ErrorActionPreference como Parar.

Criar uma mensagem de aviso ou de erro através do cmdlet Write-Warning ou Write-Error. As atividades também podem escrever nestes 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 Verboso

O Fluxo de Mensagens Verbosas destina-se a informações gerais sobre o funcionamento do runbook. Uma vez que o Fluxo de Depuração não está disponível nos runbooks, as mensagens verbosas devem ser utilizadas para informações de resolução de problemas. Por predefinição, as mensagens verbosas de runbooks publicados não são guardadas no histórico da tarefa. Para guardar mensagens verbosas, configure os runbooks publicados para Criar Registos Verbosos no separador Configurar do runbook no Portal de Gestão. Na maioria dos casos, por motivos de desempenho, deve manter a predefinição de não criar registos verbosos dos runbooks. Ative esta opção apenas para resolver problemas ou para depurar um runbook.

A predefinição da variável $VerbosePreference é um valor de SilentlyContinue. Não tem de alterar esta variável nos runbooks publicados para que as mensagens verbosas sejam guardadas. No entanto, se este valor for definido explicitamente como SilentlyContinue num runbook publicado, as mensagens verbosas não serão guardadas, mesmo que o runbook esteja configurado para criar registos verbosos.

Ao testar um runbook, as mensagens verbosas não são apresentadas, mesmo que o runbook esteja configurado para criar registos verbosos. Para apresentar mensagens verbosas enquanto testa um runbook, tem de definir a variável $VerbosePreference como Continuar. Com essa variável definida, as mensagens verbosas são apresentadas no Painel de Resultados do Teste do Portal de Gestão.

Utilize o cmdlet Write-Verbose para criar mensagens verbosas.

#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 a ser utilizado com um utilizador interativo e não deve ser utilizado em runbooks.

Registos de Progressos

Se configurar um runbook para criar registos de progressos (no separador Configurar do runbook, no Portal de Gestão), é escrito um registo no histórico da tarefa antes e depois da execução de cada atividade. Na maioria dos casos, para maximizar o desempenho, deve manter a predefinição de não criar registos de progressos dos runbooks. Ative esta opção apenas para resolver problemas ou para depurar um runbook. Ao testar um runbook, as mensagens de progresso não são apresentadas, mesmo que o runbook esteja configurado para criar registos de progressos.

O cmdlet Write-Progress não é válido num runbook, uma vez que se destina a ser utilizado com um utilizador interativo.

Variáveis de Preferências

O Windows PowerShell utiliza variáveis de preferências para determinar como responder a dados enviados para diferentes fluxos de saída. É possível definir estas variáveis num runbook, de modo a controlar o modo como este responderá a dados enviados para vários fluxos.

A tabela seguinte lista as variáveis de preferências que podem ser utilizadas em runbooks, com os respetivos valores válidos e predefinidos. Tenha em atenção que esta tabela inclui apenas os valores que são válidos em runbooks. Os valores adicionais são válidos para as variáveis de preferências quando utilizados no Windows PowerShell fora do Service Management Automation.

Variável	Valor Predefinido	Valores Válidos
WarningPreference	Continuar	Stop Continue SilentlyContinue
ErrorActionPreference	Continuar	Stop Continue SilentlyContinue
VerbosePreference	SilentlyContinue	Stop Continue SilentlyContinue

A tabela seguinte apresenta o comportamento dos valores das variáveis de preferências que são válidas nos runbooks.

Valor	Comportamento
Continuar	Regista a mensagem e continua a executar o runbook.
SilentlyContinue	Continua a executar o runbook sem registar a mensagem. Tem o efeito de ignorar a mensagem.
Parar	Regista a mensagem e suspende o runbook.

Obter Resultados e Mensagens do Runbook

Portal de Gestão

Pode ver os detalhes das tarefas dos runbooks no Portal de Gestão, no separador Tarefas dos runbooks. O Resumo da tarefa apresenta os parâmetros de entrada e o Fluxo de Saída, além das informações gerais sobre a tarefa e quaisquer exceções, caso ocorram. O Histórico incluirá mensagens do Fluxo de Saída e dos Fluxos de Avisos e de Erros, além do Fluxo Verboso e dos Registos de Progressos, se o runbook estiver configurado para criar registos verbosos e de progressos.

Windows PowerShell

No Windows PowerShell, é possível obter resultados e mensagens de um runbook com o cmdlet Get-SmaJobOutput. Este cmdlet necessita do ID da tarefa e tem um parâmetro denominado Fluxo, onde pode especificar que fluxo deve ser devolvido. Pode especificar Qualquer para devolver todos os fluxos da tarefa.

O exemplo seguinte inicia um runbook de exemplo e depois aguarda que este seja concluído. Depois de concluído, o respetivo fluxo de saída é recolhido da tarefa.

$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

Consultar Também

Expandir o Service Management Automation com runbooks
Runbook Authoring