Resultados e mensagens do runbook

A maioria dos runbooks de automatização terá alguma forma de saída, como uma mensagem de erro para o utilizador ou um objeto complexo destinado a ser consumido por outro fluxo de trabalho. Windows PowerShell fornece vários fluxos para enviar a saída de um fluxo de trabalho. A Automatização de Gestão de Serviços funciona com cada um destes fluxos de forma diferente e deve seguir as melhores práticas para utilizar cada um quando estiver a criar um runbook.

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

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. Na Automatização, este fluxo é utilizado principalmente para objetos destinados a serem consumidos por runbooks principais que chamam o runbook atual. Quando chama um runbook inline a partir de um runbook principal, este devolve dados do fluxo de saída para o 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. No entanto, como melhor prática, deve normalmente utilizar a Stream Verbosa para comunicar informações gerais ao utilizador.

Pode escrever dados no fluxo de saída com 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 esse resultado a uma variável, não será escrito 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 tipo de dados de saída

Um fluxo de trabalho pode especificar o tipo de dados da saída com 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 resultado, é uma 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 é tratado de forma diferente pela Automatização.

Selecione o separador necessário para saber mais sobre estes fluxos de mensagens:

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

#The following line creates a verbose message.

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

Registos de progresso

Se configurar um runbook para registar registos de progresso (no separador Configurar do runbook no Portal de Gestão), será escrito um registo no histórico de tarefas antes e depois de cada atividade ser executada. 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 registar registos de progresso.

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ência

Windows PowerShell utiliza variáveis de preferência para determinar como responder a dados enviados para fluxos de saída diferentes. É 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.

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

Obter Saída e Mensagens do Runbook

Portal de gestão

Pode ver os detalhes de uma tarefa de runbook no Portal de Gestão no separador Tarefas de um runbook. O Resumo da tarefa apresentará os parâmetros de entrada e a saída Stream para além das informações gerais sobre a tarefa e quaisquer exceções, caso tenham ocorrido. O Histórico incluirá mensagens do Stream de Saída e fluxos de aviso e erros, além dos Registos de Stream Verboso e Progresso se o runbook estiver configurado para registar registos verbosos e de progresso.

Windows PowerShell

No Windows PowerShell, pode obter a saída e as mensagens de um runbook com o cmdlet Get-SmaJobOutput. Este cmdlet requer o ID da tarefa e tem um parâmetro chamado Stream onde especifica o fluxo a devolver. 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

Passos seguintes

Criar runbooks de automatização.