Interagindo com Runbooks

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

Overview

RealmJoin permite que você use Azure Automation Runbooks para automatizar as operações diárias em seu ambiente. Veja 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 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 ao Portal do RealmJoin. Além disso, certifique-se de autenticar cada solicitação à API do RealmJoin usando um cabeçalho HTTP Authorization 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 trabalho é criado para esse runbook e enfileirado para execução.

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

Cada trabalho 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 como objetivo adicionar um eMail-Alias à caixa de correio de um usuário.

Cada trabalho tem um status que representa seu estado atual de execução, veja Microsoft Docs. Vamos nos concentrar em Queued, Running, Completed e Failed neste documento. Tenha em mente que isso é uma simplificação para fins de compreensão mais fácil.

Iniciando um Trabalho 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 for realmente concluído ou falhar. Este endpoint retorna diretamente o estado de sucesso e a saída do trabalho de runbook associado.

start usará os mesmos parâmetros que run mas funciona de forma assíncrona. Ele retornará assim que um trabalho de runbook for enfileirado. Ele retornará o jobID para permitir o fácil rastreamento do novo trabalho.

Nomeação de runbooks

Os runbooks são endereçados pelo nome no Azure Automation. Em resumo:

• Ele é sincronizado do repositório GitHub do RealmJoin? Adicione rjgit-como prefixo

• Ou org_, device_, group_, user_ como escopo (exatamente um deles)

• 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

Ver Convenções de Nomeação para mais detalhes.

Exemplo

Vamos assumir a seguinte situação:

• Você tem suas credenciais da API do RealmJoin e as codificou em dC0xMjM0MTIzNDpteVMzY3JldCE= (Base64)

• Você deseja 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 = "[email protected]"

  • $Revoke = $true

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

Vamos construir o solicitação:

Cabeçalhos:

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

Solicitação / URI:

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

Corpo (em notação JSON):

{ 
   "UserName": "[email protected]", 
   "Revoke": true 
}

A solicitação levará algum tempo, pois aguarda a execução do trabalho. Certifique-se de ajustar adequadamente o timeout dos seus clientes HTTP. Caso contrário, tente usar o endpoint start 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):

{
    "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 a [email protected] 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 por 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 trabalho

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

Consultando o status do trabalho

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

Ver Autenticação sobre como criar um cabeçalho de Autorização, o seguinte é apenas um exemplo.

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

Pedido

Cabeçalhos:

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

Solicitação / URI:

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.

Lendo a saída do trabalho

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 Verbose e Error fluxo. Veja lendo fluxos para ler outros fluxos. Exceções são tratados separadamente.

Ver Autenticação sobre como criar um cabeçalho de Autorização, o seguinte é apenas um exemplo.

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

Pedido

Cabeçalhos:

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

Solicitação / URI:

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 são tratados separadamente.

Ver Autenticação 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:

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

Solicitação / URI:

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, matriz de mensagens)

[
    {
        "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 Debug",
        "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

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 por um único fluxo)

Cabeçalhos:

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

Solicitação / URI:

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, matriz de mensagens)

[
    {
        "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 Debug",
        "streamType": "Verbose",
        "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, Verbose e Error fluxos. Veja lendo fluxos para ler outros fluxos.

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

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

Ver Autenticação sobre como criar um cabeçalho de Autorização, o seguinte é apenas um exemplo.

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

Pedido

Cabeçalhos:

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

Solicitação / URI:

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)

Exceção (Exceção)