Resultados e mensagens do runbook

  • Artigo

Importante

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

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 Descrição Publicado Teste
Saída 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. Apresentado no painel Saída de Teste apenas 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 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 deve ser utilizado 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. 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:

Os Fluxos de Avisos e de Erros destinam-se a registar problemas que ocorrem num runbook. São escritas no histórico de tarefas quando um runbook é executado e são incluídos no Painel de Saída de Teste no Portal de Gestão quando um runbook é testado. Por predefinição, o runbook continuará a ser executado após um aviso ou um erro. Pode especificar que o runbook deve ser suspenso num aviso ou erro ao definir uma variável de preferência no runbook antes de criar a mensagem. Por exemplo, para fazer com que um runbook suspenda um erro, uma vez que seria uma exceção, defina $ErrorActionPreference como Parar.

Crie uma mensagem de aviso ou erro com o 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."

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.

Nota

Esta tabela inclui apenas os valores válidos num runbook. Os valores adicionais são válidos para as variáveis de preferência quando utilizados no Windows PowerShell fora do Service Management Automation.

Variável Valor Predefinido Valores válidos
WarningPreference Continuar Parar
Continuar
SilentlyContinue
ErrorActionPreference Continuar Parar
Continuar
SilentlyContinue
VerbosePreference SilentlyContinue Parar
Continuar
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 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.