> 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** é 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:

```powershell
[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](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-logs.md) e mude para a **Dados de saída** guia [Detalhes do Job do Runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-logs/runbook-job-details.md) 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](#naming-a-table)) 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](#naming-a-table).

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](https://docs.realmjoin.com/pt/dev-reference/report-functions/export-rjrbxlsx.md) 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:

```plaintext
╭─ Tabela ────────────────────────────────────────────╮
│ <nome da tabela> · <contagem de linhas> linhas    │
╰───────────────────────────── → guia "Dados de saída" ──╯
```

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

```plaintext
╭─ Tabela ────────────────────────────────────────────╮
│ Dispositivos           · 3123 linhas               │
│ Credenciais de aplicativo · 42 linhas              │
│ Amostra de exportação grande · 987654 linhas       │
╰───────────────────────────── → guia "Dados de saída" ──╯
```

`→ 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:

```powershell
# Bom — objetos reais, colunas escolhidas com Select-Object
$devices | Select-Object Name, Id, OperatingSystem, LastSeen

# Ruim — registros de formatação, ocultados de Dados de saída
$devices | Format-Table Name, Id, OperatingSystem, LastSeen
```

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](#nested-objects-and-lists). |

### 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`:

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

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:

```powershell
[PSCustomObject]@{ RjTableTitle = 'Dispositivos em conformidade' }
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 planilha, e o Excel aceita apenas nomes de 1 a 31 caracteres que não contenham nenhum de `\\ / ? * [ ] :` e não comecem nem terminem com apóstrofo. Um título mais longo, como `Usuários desabilitados com uma caixa de correio compartilhada` (36 caracteres) faz a exportação falhar com *"Ocorreu um erro ao carregar os dados: sheetName 'Usuários desabilitados com uma caixa de correio compartilhada' é 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 o nome de um grupo ou uma data. Escolha títulos curtos e significativos e, quando o runbook também escrever um arquivo Excel com [Export-RjRbXlsx](https://docs.realmjoin.com/pt/dev-reference/report-functions/export-rjrbxlsx.md#worksheet-names), use o mesmo nome para a tabela e a planilha correspondente.
{% endhint %}

## 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](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-logs.md) 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](#emit-objects-not-formatted-text).

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

* [Detalhes do Job do Runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-logs/runbook-job-details.md) — a página de trabalho que hospeda as guias Console e Dados de saída.
* [Export-RjRbXlsx](https://docs.realmjoin.com/pt/dev-reference/report-functions/export-rjrbxlsx.md) — escreva os mesmos objetos em uma pasta de trabalho Excel estilizada para entrega fora do portal.
* [Send-RjRbReportEmail](https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md) — entregue os resultados do relatório aos administradores por e-mail.
* [Interagindo com Runbooks](https://docs.realmjoin.com/pt/dev-reference/interacting-with-runbooks.md) — leia a saída do trabalho programaticamente pela API 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=<question>&goal=<user_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.
