> 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/interacting-with-runbooks.md).

# Interagir com runbooks

Executar runbooks e consultar o respetivo estado usando a API do RealmJoins

## Visão geral

RealmJoin permite que você use Runbooks do Azure Automation para automatizar operações do dia a dia em seu ambiente. Veja [Runbooks](https://docs.realmjoin.com/pt/automatizacao/runbooks.md) para mais informações.

A API do RealmJoin permite que você inicie runbooks a partir da sua aplicação, para consultar a execução bem-sucedida de execuções acionadas anteriormente. Veja [a referência da API do RealmJoin](https://customer-api.realmjoin.com/scalar/v1) para ver quais operações são atualmente suportadas.

As seções a seguir mostram como usar a API do RealmJoin para iniciar e acompanhar jobs de runbook. Assume-se que você já tenha [conectado uma conta do Azure Automation](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation.md) ao Portal do RealmJoin. Além disso, certifique-se de [autenticar ](https://docs.realmjoin.com/pt/dev-reference/realmjoin-api/authentication.md)cada solicitação à API do RealmJoin usando um cabeçalho de autorização HTTP apropriado.

## Como o Azure Automation lida com runbooks?

O Azure Automation tem uma abordagem de processamento em lote em relação a runbooks. Quando você aciona a execução de um runbook, um job é criado para esse runbook e colocado na fila para execução.

Portanto, em geral, um runbook não será iniciado imediatamente. Além disso, vários jobs para o mesmo runbook podem existir ao mesmo tempo em diferentes estados de execução.

Todo job tem um conjunto de parâmetros (entradas) que são passados para o script do runbook. Isso pode, por exemplo, ser duas variáveis como `$username` e `$newEmailAddress` se o runbook tiver de adicionar um alias de e-mail à caixa de correio de um usuário.

Todo job tem um status que representa seu estado atual de execução; veja [Microsoft Docs](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). Vamos nos concentrar em `Em fila`, `Em execução`, `Concluído` e `Falhou` neste documento. Esteja ciente de que esta é uma simplificação para facilitar a compreensão.

## Iniciando um job de runbook

A API do RealmJoin oferece dois endpoints para acionar runbooks.

`run` executará um runbook de forma síncrona e só retornará/terminará quando o runbook estiver realmente concluído ou com falha. Este endpoint retorna diretamente o estado de sucesso e a saída do job de runbook associado.

`start` terá os mesmos parâmetros que `run` mas funciona de forma assíncrona. Ele retornará assim que um job de runbook for colocado na fila. Ele retornará o `jobID` para permitir o fácil acompanhamento do novo job.

### Nomenclatura de runbook

Os runbooks são referenciados pelo nome no Azure Automation. Em resumo:

* É sincronizado a partir do repositório GitHub do RealmJoin? Adicione `rjgit-`como prefixo
* Ou `org_`, `device_`, `group_`, `user_` como escopo (exatamente um desses)
* Uma categoria, como `general_`ou `security_`
* O nome do runbook, separado por `_` como `add-xyz-exception`

O resultado, neste caso, seria: `rjgit-org_security_add-xyz-exception`

Veja [Convenções de Nomenclatura](https://docs.realmjoin.com/pt/automatizacao/runbooks/naming-conventions.md) para mais detalhes.

### Exemplo

Suponha a seguinte situação:

* Você tem suas credenciais da API do RealmJoin e as codificou para `dC0xMjM0MTIzNDpteVMzY3JldCE=` (Base64)
* Você quer iniciar o runbook `rjgit-user_security_revoke-or-restore-access` para bloquear o login de um usuário específico
* Os parâmetros para o runbook (PowerShell) são:
  * `$UserName = "someone@contoso.com"`
  * `$Revoke = $true`

Usaremos o `run` endpoint para saber imediatamente se o job foi bem-sucedido.

Vamos montar a **solicitação**:

Cabeçalhos:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Solicitação / URI:

```http
POST https://customer-api.realmjoin.com/runbook/rjgit-user_security_revoke-or-restore-access/run
```

Corpo (em notação JSON):

```json
{ 
   "UserName": "someone@contoso.com", 
   "Revoke": true 
}
```

A solicitação levará algum tempo, pois aguarda a execução do job. Certifique-se de ajustar adequadamente o timeout dos seus clientes HTTP. Caso contrário, tente usar o `start` endpoint, que retornará imediatamente.

A resposta conterá o `jobID`, o `status` (`Falhou` ou `Concluído`) e todos os fluxos de saída do runbook.

**Resposta**:

Status HTTP: `200` (OK)

Corpo (em notação JSON):

```json
{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Concluído",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Executando na conta do Azure Automation",
            "streamType": "Detalhado",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Obtendo a conexão de automação 'AzureRunAsConnection'",
            "streamType": "Detalhado",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: Conectando com o módulo AzureAD: ...",
            "streamType": "Detalhado",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## O acesso do usuário para someone@contoso.com foi revogado.",
            "streamType": "Saída",
            "streamText": null,
            "value": null
        }
    ]
}
```

Os fluxos de saída são separados em diferentes canais (`streamTypes`): `Saída`, `Detalhado`, `Erro`. Isso permite filtrar erros ou reduzir a saída apenas às informações relevantes, exibindo apenas `Saída`.

Você pode obter esses fluxos após a conclusão de um runbook usando o `/runbook/jobs/{jobID}/output/streams` endpoint. (veja abaixo)

## Consultando o status e a saída de um job

Se um job já tiver sido criado, você pode usar a API do RealmJoin para consultar seu estado e saída.

### Consultando o status do job

Use `/runbook/jobs/{jobID}/status` para consultar o status atual.

Veja [Autenticação ](https://docs.realmjoin.com/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho de autorização, o seguinte é apenas um exemplo.

Suponha que o `jobID` seja `1234545e-7a24-436a-90c9-6056b512345`

**`Solicitar`**

Cabeçalhos:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Solicitação / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/status
```

Esta solicitação não tem corpo.

**Resposta**

Status HTTP 200 (OK)

Corpo (texto simples)

```
Concluído
```

Outros estados possíveis incluem `Novo`, `Falhou`, `Em execução`. Veja [estados possíveis do Runbook](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses).

### Lendo a saída do job

Use `/runbook/jobs/{jobID}/output/text` para obter uma representação simples em texto puro da saída de um runbook. Isso não incluirá o `Detalhado` e `Erro` fluxo. Veja [leitura de fluxos](#reading-specific-streams) para ler outros fluxos. [Exceções](#reading-exceptions) são tratadas separadamente.

Veja [Autenticação ](https://docs.realmjoin.com/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho de autorização, o seguinte é apenas um exemplo.

Suponha que o `jobID` seja `1234545e-7a24-436a-90c9-6056b512345`

**Solicitar**

Cabeçalhos:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Solicitação / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/text
```

Esta solicitação não tem corpo.

**Resposta**

Status HTTP 200 (OK)

Corpo (texto simples)

```
## O Grupo de Distribuição 'Equipe de Vendas' foi criado.
```

### Lendo fluxos específicos

Use `/runbook/jobs/{jobID}/output/streams` para obter uma representação JSON abrangente da saída de um runbook. Dessa forma, você pode acessar o `Saída`, `Detalhado` e `Erro` fluxo. [Exceções](#reading-exceptions) são tratadas separadamente.

Veja [Autenticação ](https://docs.realmjoin.com/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho de autorização, o seguinte é apenas um exemplo.

Suponha que o `jobID` seja `1234545e-7a24-436a-90c9-6056b512345`

**Solicitação (todos os fluxos)**

Cabeçalhos:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Solicitação / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams
```

Esta solicitação não tem corpo.

**Resposta**

Status HTTP 200 (OK)

Corpo (JSON, array de mensagens)

```json
[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Carregando módulo do caminho 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Carregando módulo do caminho 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Executando na conta do Azure Automation",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Saída normal",
        "streamType": "Saída",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Mensagem detalhada ou de depuração",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Mensagem de erro não interruptiva",
        "streamType": "Erro",
        "streamText": null,
        "value": null
    }
]
```

Veja abaixo para ler mensagens de erro interruptivas e [exceções](#reading-exceptions)

Para receber apenas um único fluxo, por exemplo Verbose, você pode adicionar um filtro à solicitação adicionando `?streamTypes=Verbose`. Você também pode filtrar por `Saída` e `Erro`.

**Solicitação (filtrar por um único fluxo)**

Cabeçalhos:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Solicitação / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams?streamTypes=Verbose
```

Esta solicitação não tem corpo.

**Resposta**

Status HTTP 200 (OK)

Corpo (JSON, array de mensagens)

```json
[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Carregando módulo do caminho 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Carregando módulo do caminho 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Executando na conta do Azure Automation",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Mensagem detalhada ou de depuração",
        "streamType": "Detalhado",
        "streamText": null,
        "value": null
    }
]
```

### Lendo exceções

Use `/runbook/jobs/{jobID}/exception/text` para obter uma representação simples em texto puro da mensagem de exceção de um runbook (se houver). Isso não incluirá os `Saída`, `Detalhado` e `Erro` fluxos. Veja [leitura de fluxos](#reading-specific-streams) para ler outros fluxos.

As exceções são registradas quando ocorrem erros interruptivos na execução do script PowerShell associado ao runbook. Este endpoint lerá apenas a mensagem em texto puro e não incluirá detalhes técnicos, como em qual linha de código o script foi interrompido.

No nosso exemplo, um erro interruptivo foi causado por `throw "Exception"`.

Veja [Autenticação ](https://docs.realmjoin.com/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho de autorização, o seguinte é apenas um exemplo.

Suponha que o `jobID` seja `1234545e-7a24-436a-90c9-6056b512345`

**Solicitar**

Cabeçalhos:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Solicitação / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/exception/text
```

Esta solicitação não tem corpo.

**Resposta**

Status HTTP 200 (OK)

Corpo (texto simples)

```
Exceção (Exception)
```


---

# 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/interacting-with-runbooks.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.
