For the complete documentation index, see llms.txt. This page is also available as Markdown.

Dados de saída de runbook

Apresentar os resultados dos runbooks como tabelas ordenáveis e filtráveis no RealmJoin Portal e escrever runbooks que emitam objetos estruturados.

Visão geral

Dados de saída é o equivalente estruturado de Consola guia em uma página de trabalho de runbook. O console mantém o feed de texto bruto, linha a linha, de uma execução; Dados de saída renderiza os objetos que a mesma execução emitiu como tabelas. Valores longos, como GUIDs, são mostrados por completo em vez de serem truncados para … pelo formatador do console do PowerShell, e conjuntos de resultados largos permanecem legíveis em vez de serem quebrados.

Caraterísticas principais:

  • Sem configuração, sem permissões adicionais — a guia está disponível para todo runbook que emite objetos. Nada precisa ser habilitado, e quem pode iniciar um runbook não é afetado.

  • Objetos em vez de texto pré-formatado — as tabelas são criadas a partir do que o runbook escreve no fluxo de saída. Um runbook que pré-formata seus resultados com Format-Table não produz nenhum dado de saída.

  • Tabelas interativas — cada tabela pode ser classificada, filtrada, paginada e exportada para Excel ou CSV independentemente das outras.

  • Dados aninhados permanecem inspecionáveis — objetos e arrays dentro de uma célula são expansíveis em vez de achatados em uma única string ilegível.

  • A guia Console permanece inalterada — a saída de texto completa continua disponível e pode ser copiada, que é o que um chamado de serviço ou ITIL geralmente precisa.

Início rápido

O runbook mínimo viável emite um objeto marcador com o nome da tabela e, em seguida, os dados:

[PSCustomObject]@{ RjTableTitle = 'Dispositivos não conformes' }
Write-Output $nonCompliantDevices

Isso produz uma tabela intitulada Dispositivos não conformes na guia Dados de saída — uma linha por dispositivo, uma coluna por propriedade — além de uma linha de resumo compacta na guia Console que aponta para ela.

Lendo Dados de saída no Portal

Abra um trabalho em Registos de Runbook e mude para a Dados de saída guia Detalhes do Job do Runbook para as outras guias dessa página.

Tabelas e navegação

Cada conjunto de objetos que um runbook emite se torna uma tabela. Uma tabela contém:

  • Um título — o nome que o runbook definiu (veja Nomeando uma tabela) ou o fallback Tabela 1, Tabela 2 e assim por diante.

  • Uma entrada na barra lateral — cada tabela é listada à esquerda; clicar em um título leva até ela.

  • Um contador de linhas — 12 / 340 linhas mostra quantas linhas correspondem ao filtro atual em relação ao total da tabela.

Filtro

O Filtrar… caixa acima de uma tabela mantém apenas as linhas que contêm o texto inserido. O filtro é uma correspondência de substring sem considerar maiúsculas e minúsculas em todas as colunas dessa tabela. Cada tabela é filtrada independentemente.

Classificar

Clicar no cabeçalho de uma coluna classifica por essa coluna; clicar novamente inverte a direção. Uma seta (▲ / ▼) marca a coluna ativa. A ordenação considera o tipo:

Conteúdo da coluna
Ordem de classificação

Números

Numérica — 2 antes de 10.

Datas

Cronológica.

Todo o resto

Alfabética, sem considerar maiúsculas e minúsculas.

Células vazias aparecem primeiro.

Paginação

As tabelas são paginadas em blocos de 50 linhas, com um paginador abaixo da tabela. Filtro e ordenação sempre se aplicam à tabela inteira, não apenas à página exibida no momento.

Objetos e listas aninhados

Uma célula que contém um objeto ou array aninhado não é achatada em texto ilegível:

  • A célula mostra um acento circunflexo (▸). Clicar nele expande esse objeto ou array inline abaixo da linha.

  • O cabeçalho da coluna traz uma seta de expansão. Clicar nele expande a coluna inteira em sua própria tabela: o valor aninhado de cada linha pai é transformado em linhas, e uma coluna de referência aponta de volta para o número da linha pai. A nova tabela é anexada ao final da página e à barra lateral, e pode ser filtrada, classificada e exportada como qualquer outra.

Exportar

Cada tabela tem seus próprios botões Exportar para Excel (.xlsx) e Exportar para CSV . As exportações respeitam o filtro ativo — apenas as linhas correspondentes são gravadas — e usam o título da tabela como nome do arquivo. Exportar para Excel também usa o título como nome da planilha e falha para títulos com mais de 31 caracteres, veja Nomeando uma tabela.

Exportar pelo portal cobre o caso ad hoc. Para arquivos de relatório que um runbook deve entregar por conta própria — como anexo de e-mail ou como link de download — construa-os no próprio runbook, com Export-RjRbXlsx e os auxiliares de entrega.

Guia Console

Quando um trabalho emitiu tabelas, a Consola guia mostra uma visão compactada por padrão. As tabelas são desenhadas no estilo PowerShell, mas truncadas, para que as linhas de status permaneçam legíveis e um runbook que emitiu centenas de objetos não inunde a página. No lugar de cada tabela, o console mostra uma caixa de resumo:

As tabelas emitidas em sucessão direta compartilham uma única caixa:

→ guia "Dados de saída" é um link e muda para a tabela correspondente.

Dois botões controlam a visualização:

  • Mostrar saída completa — alterna para o texto completo, sem truncamento.

  • Mostrar tabelas compactadas — volta.

Copiar para a área de transferência sempre copia a saída bruta completa, independentemente da visualização mostrada.

Emitindo Dados de saída a partir de um runbook

A guia é construída a partir dos objetos que um runbook emite. Portanto, tabelas limpas exigem que o runbook escreva objetos em vez de pré-formatá-los em texto.

Emita objetos, não texto formatado

Nunca canalize a saída por Format-Table ou Format-List. Esses cmdlets emitem registros do mecanismo de formatação, não dados. O portal os detecta e os oculta, e mostra uma dica de que a saída foi formatada incorretamente. O mesmo se aplica em qualquer lugar em que o PowerShell formate automaticamente um resultado porque ele foi escrito no host em vez de no fluxo de saída.

Format-* cmdlets só controlam a exibição. O que eles foram usados para tem um equivalente em dados que a guia Dados de saída pode renderizar — escolher colunas, em particular, é o que Select-Object faz:

Em vez de
Utilize

$devices | Format-Table Name, Id

$devices | Select-Object Name, Id

$devices | Format-Table -AutoSize

Write-Output $devices

$devices | Format-List

Write-Output $devices

Select-Object Name, Id produz a mesma seleção de colunas que Format-Table Name, Id teria exibido — mas ele emite objetos, então as colunas sobrevivem na guia Dados de saída em vez de serem descartadas como registros de formatação:

As propriedades selecionadas são exatamente as colunas da tabela resultante: Nome, Id, OperatingSystem e LastSeen, uma linha por dispositivo.

Como os objetos se tornam tabelas

Emitido
Renderizado como

Um objeto

Uma linha — suas propriedades se tornam as colunas.

Objetos consecutivos com as mesmas propriedades

Uma tabela.

Um objeto com um conjunto diferente de propriedades

Uma nova tabela é iniciada.

Um único valor simples (string, número)

Uma linha de texto no console, não uma tabela.

Uma linha que começa com ## seguida de um espaço

Um cabeçalho na visualização do console.

Um objeto ou array aninhado

JSON na célula, expansível na grade — veja Objetos e listas aninhados.

Nomeando uma tabela

Por padrão, as tabelas são rotuladas Tabela 1, Tabela 2 e assim por diante. Para dar a uma tabela um nome significativo, o runbook emite um objeto marcador imediatamente antes dos dados. O marcador é um objeto com uma única propriedade, cuja única propriedade é RjTableTitle:

A tabela a seguir recebe então o título Dispositivos não conformes — no cabeçalho, na barra lateral e no nome do arquivo exportado.

  • O próprio marcador é consumido. Ele não aparece nem como linha nem como linha do console.

  • O nome da propriedade é insensível a maiúsculas e minúsculas — RjTableTitle, rjtabletitle e qualquer outra capitalização também funciona.

  • Uma vazio é ignorado, então um marcador vazio não pode apagar um nome existente.

  • O nome se aplica à próxima tabela emitida, mesmo quando linhas de status aparecem entre elas.

Repetir o padrão nomeia várias tabelas em uma única execução:

Comportamento e limitações

Trabalhos arquivados

Dados de saída está disponível apenas para execuções ao vivo. Um trabalho arquivado mostra "Os dados estruturados não podem ser recuperados de uma execução arquivada." — esses resultados precisam ser lidos na guia Console. Veja Registos de Runbook para a distinção entre logs de trabalhos recentes e arquivados.

Runbooks sem saída estruturada

"Nenhum dado de saída estruturado deste runbook." significa que nada em formato de tabela foi emitido. Se um ícone de informação acompanha a mensagem, o runbook enviou registros de formatação do PowerShell em vez de dados — veja Emita objetos, não texto formatado.

Valores únicos

Um runbook que emite um único valor simples — uma string de status, uma contagem — mantém esse valor como uma linha de texto na guia Console. Só objetos se tornam tabelas, então mensagens de progresso e status não se transformam cada uma em uma tabela de uma linha.

Ver também

Última atualização

Isto foi útil?