> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/dev-reference/runbook-output-data.md). # 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** é a contraparte estruturada do **Console** separador na página de um trabalho de runbook. A consola mantém o feed de texto bruto, linha a linha, de uma execução; os Dados de Saída apresentam os objetos que a mesma execução emitiu como tabelas. Valores longos, como GUIDs, são mostrados na íntegra em vez de serem truncados para `…` pelo formatador da consola do PowerShell, e conjuntos de resultados largos continuam legíveis em vez de serem quebrados em várias linhas. Características principais: * **Sem configuração, sem permissões adicionais** — o separador está disponível para todos os runbooks que emitem objetos. Nada precisa de ser ativado, e quem pode iniciar um runbook não é afetado. * **Objetos em vez de texto pré-formatado** — as tabelas são construídas a partir do que o runbook escreve no fluxo de saída. Um runbook que pré-formata os seus resultados com `Format-Table` não produz quaisquer Dados de Saída. * **Tabelas interativas** — cada tabela pode ser ordenada, filtrada, paginada e exportada para Excel ou CSV, independentemente das outras. * **Os dados aninhados continuam a poder ser inspecionados** — objetos e matrizes dentro de uma célula são expansíveis, em vez de serem achatados numa única cadeia ilegível. * **O separador Consola não se altera** — a saída de texto completa continua disponível e pode ser copiada, o que é normalmente o que um pedido de serviço ou ticket ITIL precisa. ## Início rápido O runbook mínimo viável emite um objeto marcador com o nome da tabela e, depois, os dados: ```powershell [PSCustomObject]@{ RjTableTitle = 'Dispositivos não conformes' } Write-Output $nonCompliantDevices ``` Isto produz uma tabela intitulada **Dispositivos não conformes** no separador Dados de Saída — uma linha por dispositivo, uma coluna por propriedade — além de uma linha de resumo compacta no separador Consola que aponta para ela. ## Ler os Dados de Saída no Portal Abra um trabalho de [Runbook Logs](/pt/automatizacao/runbooks/runbook-logs.md) e mude para o separador **Dados de Saída** Veja [Detalhes do Trabalho do Runbook](/pt/automatizacao/runbooks/runbook-logs/runbook-job-details.md) para os outros separadores dessa página. ### Tabelas e navegação Cada conjunto de objetos que um runbook emite torna-se uma tabela. Uma tabela contém: * **Um título** — ou o nome definido pelo runbook (ver [Dar nome a uma tabela](#naming-a-table)) ou a alternativa `Tabela 1`, `Tabela 2` e assim por diante. * **Uma entrada na barra lateral** — todas as tabelas são তাল no lado esquerdo; clicar num título salta para ela. * **Um contador de linhas** — `12 / 340 linhas` mostra quantas linhas correspondem ao filtro atual, do total da tabela. ### Filtrar A caixa **Filtrar…** acima de uma tabela mantém apenas as linhas que contêm o texto introduzido. O filtro é uma correspondência de substring sem distinção entre maiúsculas e minúsculas em todas as colunas dessa tabela. Cada tabela filtra de forma independente. ### Ordenar Clicar no cabeçalho de uma coluna ordena por essa coluna; clicar novamente inverte a direção. Uma seta (`▲` / `▼`) marca a coluna ativa. A ordenação é sensível ao tipo: | Conteúdo da coluna | Ordem de ordenação | | ------------------ | -------------------------------------------------------- | | Números | Numérica — `2` antes `10`. | | Datas | Cronológica. | | Tudo o resto | Alfabética, sem distinção entre maiúsculas e minúsculas. | As células vazias aparecem primeiro na ordenação. ### Paginação As tabelas são paginadas a 50 linhas, com um paginador por baixo da tabela. Filtrar e ordenar aplicam-se sempre à tabela inteira, e não apenas à página atualmente mostrada. ### Objetos e listas aninhados Uma célula que contém um objeto ou matriz aninhados não é achatada em texto ilegível: * A célula mostra um caret (`▸`). Clicar nele expande esse objeto ou matriz em linha, por baixo da linha. * O cabeçalho da coluna contém uma seta de expansão. Clicar nela expande a coluna inteira para a sua própria tabela: o valor aninhado de cada linha-pai é desdobrado em linhas, e uma coluna de referência liga de volta ao número da linha-pai. A nova tabela é anexada no fundo da página e na barra lateral, e pode ser filtrada, ordenada e exportada como qualquer outra. ### Exportar Cada tabela tem o seu próprio **Exportar para Excel** (`.xlsx`) e **Exportar para CSV** botões. As exportações respeitam o filtro ativo — apenas as linhas correspondentes são escritas — e usam o título da tabela como nome do ficheiro. A exportação para Excel também usa o título como nome da folha e falha para títulos com mais de 31 caracteres, veja [Dar nome a uma tabela](#naming-a-table). Exportar a partir do portal cobre o caso ad hoc. Para ficheiros de relatório que um runbook deve entregar por si só — como anexo de email ou como ligação de transferência — construa-os no runbook, em vez disso, com [Export-RjRbXlsx](/pt/dev-reference/report-functions/export-rjrbxlsx.md) e os auxiliares de entrega. ## Separador Consola Quando um trabalho emitiu tabelas, o separador **Console** mostra por predefinição uma vista comprimida. As tabelas são desenhadas ao estilo do PowerShell, mas truncadas, para que as linhas de estado se mantenham legíveis e um runbook que emitiu centenas de objetos não inunde a página. Em vez de cada tabela, a consola mostra uma caixa de resumo: ```plaintext ╭─ Table ────────────────────────────────────────────╮ │ · rows │ ╰───────────────────────────── → "Output Data" tab ──╯ ``` Tabelas emitidas em sucessão direta partilham uma única caixa: ```plaintext ╭─ Table ────────────────────────────────────────────╮ │ Devices · 3123 rows │ │ Application credentials · 42 rows │ │ Large export sample · 987654 rows │ ╰───────────────────────────── → "Output Data" tab ──╯ ``` `→ "Output Data" tab` é uma ligação e muda para a tabela correspondente. Dois botões controlam a vista: * **Mostrar saída completa** — mudar para o texto completo, sem truncatura. * **Mostrar tabelas comprimidas** — voltar atrás. **Copiar para a área de transferência** copia sempre a saída bruta completa, independentemente da vista mostrada. ## Emitir Dados de Saída a partir de um Runbook O separador é construído a partir dos objetos que um runbook emite. Tabelas limpas, portanto, exigem que o runbook escreva objetos em vez de os pré-formatar em texto. ### Emita objetos, não texto formatado > **Nunca encaminhe a saída através de `Format-Table` ou `Format-List`.** Esses cmdlets emitem registos do motor de formatação, não dados. O portal deteta-os e oculta-os, e mostra uma dica de que a saída foi mal formatada. O mesmo se aplica em qualquer situação em que o PowerShell auto-formate um resultado porque foi escrito para o host em vez de para o fluxo de saída. `Format-*` cmdlets apenas controlam a *apresentação*. O para que foram usados tem um equivalente em dados que os Dados de Saída podem apresentar — escolher colunas, em particular, é o que `Select-Object` faz: | Em vez de | Use | | ------------------------------------ | ------------------------------------ | | `$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` iria mostrar — mas emite objetos, pelo que as colunas sobrevivem no separador Dados de Saída em vez de serem descartadas como registos de formatação: ```powershell # Bom — objetos reais, colunas escolhidas com Select-Object $devices | Select-Object Name, Id, OperatingSystem, LastSeen # Mau — registos de formatação, ocultos dos Dados de Saída $devices | Format-Table Name, Id, OperatingSystem, LastSeen ``` As propriedades selecionadas são exatamente as colunas da tabela resultante: `Name`, `Id`, `OperatingSystem` e `LastSeen`, uma linha por dispositivo. ### Como os objetos se tornam tabelas | Emitido | Apresentado como | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Um objeto | Uma linha — as suas propriedades tornam-se as colunas. | | Objetos consecutivos com as mesmas propriedades | Uma tabela. | | Um objeto com um conjunto diferente de propriedades | Inicia-se uma nova tabela. | | Um único valor simples (string, número) | Uma linha de texto na consola, não uma tabela. | | Uma linha que começa com `##` seguido de um espaço | Um cabeçalho na vista da consola. | | Um objeto ou matriz aninhados | JSON na célula, expansível na grelha — veja [Objetos e listas aninhados](#nested-objects-and-lists). | ### Dar nome a uma tabela Por predefiniçã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`: ```powershell [PSCustomObject]@{ RjTableTitle = 'Dispositivos não conformes' } Write-Output $nonCompliantDevices ``` A tabela seguinte fica então intitulada **Dispositivos não conformes** — no cabeçalho, na barra lateral e no nome do ficheiro de exportação. * O próprio marcador é **consumido**. Não aparece nem como linha nem como linha de consola. * O nome da propriedade é **insensível a maiúsculas e minúsculas** — `RjTableTitle`, `rjtabletitle` e qualquer outra capitalização funciona. * Um **vazio** título é ignorado, pelo que um marcador vazio não pode apagar um nome existente. * O nome aplica-se à **seguinte** tabela emitida, mesmo quando aparecem linhas de estado pelo meio. Repetir o padrão nomeia várias tabelas numa única execução: ```powershell [PSCustomObject]@{ RjTableTitle = 'Dispositivos conformes' } Write-Output $compliant [PSCustomObject]@{ RjTableTitle = 'Dispositivos não conformes' } Write-Output $nonCompliant ``` {% hint style="warning" %} **Mantenha os títulos das tabelas com no máximo 31 caracteres.** **Exportar para Excel** usa o título da tabela como nome da folha, e o Excel aceita apenas nomes de 1 a 31 caracteres que não contenham nenhum de `\ / ? * [ ] :` e que não comecem nem terminem com um apóstrofo. Um título mais longo, como `Utilizadores desativados com uma caixa de correio partilhada` (36 caracteres) faz a exportação falhar com *"Ocorreu um erro ao carregar os dados: sheetName 'Utilizadores desativados com uma caixa de correio partilhada' é inválido - a contagem de caracteres DEVE ser maior ou igual a 1 e menor ou igual a 31"*. O limite inclui valores inseridos em tempo de execução, como um nome de grupo ou uma data. Escolha títulos curtos e significativos e, quando o runbook também escreve um ficheiro Excel com [Export-RjRbXlsx](/pt/dev-reference/report-functions/export-rjrbxlsx.md#worksheet-names), use o mesmo nome para a tabela e para a folha correspondente. {% endhint %} ## Comportamento e limitações ### Trabalhos arquivados Os Dados de Saída estão disponíveis apenas para execuções em curso. Um trabalho arquivado mostra *"Não é possível obter dados estruturados de uma execução arquivada."* — esses resultados têm de ser lidos no separador Consola. Veja [Runbook Logs](/pt/automatizacao/runbooks/runbook-logs.md) para a distinção entre registos de trabalho recentes e arquivados. ### Runbooks sem saída estruturada *"Nenhum dado de saída estruturado deste runbook."* significa que nada em forma de tabela foi emitido. Se um ícone de informação acompanhar a mensagem, o runbook enviou registos de formatação do PowerShell em vez de dados — veja [Emita objetos, não texto formatado](#emit-objects-not-formatted-text). ### Valores únicos Um runbook que emite um único valor simples — uma string de estado, uma contagem — mantém esse valor como uma linha de texto no separador Consola. Só os objetos se tornam tabelas, por isso as mensagens de progresso e estado não se transformam cada uma numa tabela de uma linha. ## Ver também * [Detalhes do Trabalho do Runbook](/pt/automatizacao/runbooks/runbook-logs/runbook-job-details.md) — a página de trabalho que aloja os separadores Consola e Dados de Saída. * [Export-RjRbXlsx](/pt/dev-reference/report-functions/export-rjrbxlsx.md) — escreva os mesmos objetos para um livro do Excel com estilo para entrega fora do portal. * [Send-RjRbReportEmail](/pt/dev-reference/report-functions/send-rjrbreportemail.md) — entregue os resultados do relatório aos administradores por email. * [Interagir com Runbooks](/pt/dev-reference/interacting-with-runbooks.md) — leia programaticamente a saída do trabalho através da API do RealmJoin. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.realmjoin.com/pt/dev-reference/runbook-output-data.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.