# Interagir com Runbooks

## Vista geral

RealmJoin permite que você use Azure Automation Runbooks para automatizar as operações do dia a dia no seu ambiente. Veja [Runbooks](https://docs.realmjoin.com/pt/automacao/runbooks) 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 descrição Swagger do RealmJoin](https://customer-api.realmjoin.com/swagger/index.html) para ver quais operações são atualmente suportadas.

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

## Como o Azure Automation lida com runbooks?

O Azure Automation adota uma abordagem de processamento em lote em relação aos 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 iniciará imediatamente. Além disso, vários jobs para o mesmo runbook podem existir ao mesmo tempo em diferentes estados de execução.

Cada 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 for suposto adicionar um alias de e-mail à caixa de correio de um usuário.

Cada 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 `Queued`, `Running`, `Completed` e `Failed` neste documento. Esteja ciente de que isso é 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 falhado. Este endpoint retorna diretamente o estado de sucesso e a saída do job de runbook associado.

`start` usará 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 acompanhamento fácil do novo job.

### Nomeação de runbook

Os runbooks são endereçados pelo seu nome no Azure Automation. Resumindo:

* É sincronizado a partir do repositório GitHub do RealmJoin? Adicione `prefixo rjgit-`como prefixo
* Ou seja, `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`

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

### Exemplo

Vamos supor a seguinte situação:

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

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

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

Cabeçalhos:

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

Requisiçã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 adaptar o timeout dos seus clientes HTTP de acordo. Caso contrário, tente usar o `start` endpoint, que retornará imediatamente.

A resposta conterá o `jobID`, o `status` (`Failed` ou `Completed`) 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": "Completed",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Executando na conta do Azure Automation",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Obtendo conexão de automação 'AzureRunAsConnection'",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: Conectando com o módulo AzureAD: ...",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## O acesso do usuário someone@contoso.com foi revogado.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}
```

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

Você pode obter esses fluxos depois que um runbook terminar 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.

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

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

**`Pedido`**

Cabeçalhos:

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

Requisiçã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**

Http Status 200 (OK)

Corpo (texto simples)

```
Completed
```

Outros estados possíveis incluem `New`, `Failed`, `Running`. 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 da saída de um runbook. Isso não incluirá o `Verbose` e `Error` fluxo. Veja [leitura de fluxos](#reading-specific-streams) para ler outros fluxos. [Exceções](#reading-exceptions) são tratados separadamente.

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

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

**Pedido**

Cabeçalhos:

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

Requisiçã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**

Http Status 200 (OK)

Corpo (texto simples)

```
## O grupo de distribuição 'Sales Team' 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`, `Verbose` e `Error` fluxo. [Exceções](#reading-exceptions) são tratados separadamente.

Consulte [Autenticação ](https://docs.realmjoin.com/pt/dev-reference/realmjoin-api/authentication)sobre como criar um cabeçalho Authorization, 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
```

Requisiçã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**

Http Status 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": "Verbose",
        "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": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Executando na conta do Azure Automation",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Saída normal",
        "streamType": "Output",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Mensagem Verbose ou de depuração",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Mensagem de erro não interruptiva",
        "streamType": "Error",
        "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 `Error`.

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

Cabeçalhos:

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

Requisiçã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**

Http Status 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": "Verbose",
        "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": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Executando na conta do Azure Automation",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Mensagem Verbose ou de depuração",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]
```

### Lendo exceções

Use `/runbook/jobs/{jobID}/exception/text` para obter uma representação simples em texto da mensagem de exceção de um runbook (se houver). Isso não incluirá os `Saída`, `Verbose` e `Error` 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 simples e não inclui detalhes técnicos, como em qual linha de código o script parou.

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

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

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

**Pedido**

Cabeçalhos:

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

Requisiçã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**

Http Status 200 (OK)

Corpo (texto simples)

```
Exception (Exception)
```