Interação com runbooks

Execute runbooks e consulte o seu estado usando a API do RealmJoin

Visão geral

RealmJoin permite usar Runbooks do Azure Automation para automatizar as operações do dia a dia no seu ambiente. Veja Runbooks para mais informações.

A API do RealmJoin permite iniciar 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 descrevem 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 ao Portal 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 trata 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 será iniciado 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 ao script do runbook. Isso pode, por exemplo, ser duas variáveis como $username e $newEmailAddress se o runbook deve 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. Vamos nos concentrar em Na fila, Em execução, Concluído e Falhou neste documento. Observe 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 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 enfileirado. Ele retornará o jobID para permitir o acompanhamento fácil do novo job.

Nomeação de runbooks

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

• É sincronizado do repositório GitHub do RealmJoin? Adicione prefixo rjgit-como prefixo
• Ou org_, device_, group_, user_ como escopo (exatamente um destes)
• 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 Nomenclatura 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ê quer iniciar o runbook rjgit-user_security_revoke-or-restore-access para bloquear o login de um usuário específico
• Os parâmetros do runbook (PowerShell) são:

  • $UserName = "[e-mail]"
  • $Revoke = $true

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

Vamos construir o solicitar:

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": "[e-mail]", 
   "Revoke": true 
}

A solicitação levará algum tempo, pois aguarda a execução do job. Certifique-se de ajustar adequadamente o timeout do seu cliente 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 streams de saída do runbook.

Resposta:

Status HTTP: 200 (OK)

Corpo (em notação 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": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Obtendo a 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 [e-mail] foi revogado.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}

Os streams 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 streams 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 sua saída.

Consultando o status do job

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.

Assuma o jobID como sendo 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

Status HTTP 200 (OK)

Corpo (texto simples)

Concluído

Outros estados possíveis incluem Novo, Falhou, Em execução. Consulte estados possíveis de Runbook.

Lendo a saída do job

Use /runbook/jobs/{jobID}/output/text para obter uma representação simples em texto simples da saída de um runbook. Isso não incluirá o Verbose e Error stream. Veja leitura de streams para ler outros streams. Exceções são tratados separadamente.

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

Assuma o jobID como sendo 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

Status HTTP 200 (OK)

Corpo (texto simples)

## O grupo de distribuição 'Sales Team' foi criado.

Lendo streams específicos

Use /runbook/jobs/{jobID}/output/streams para obter uma representação JSON completa da saída de um runbook. Dessa forma, você pode acessar o Saída, Verbose e Error stream. Exceções são tratados separadamente.

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

Assuma o jobID como sendo 1234545e-7a24-436a-90c9-6056b512345

Solicitação (todos os streams)

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

Status HTTP 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 regular",
        "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": "Erro",
        "streamText": null,
        "value": null
    }
]

Veja abaixo para ler mensagens de erro interruptivas e exceções

Para receber apenas um único stream, 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 stream)

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

Status HTTP 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 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 simples da mensagem de exceção de um runbook (se houver). Isso não incluirá os Saída, Verbose e Error streams. Veja leitura de streams para ler outros streams.

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 que linha de código o script foi interrompido.

No 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.

Assuma o jobID como sendo 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

Status HTTP 200 (OK)

Corpo (texto simples)

Exceção (Exception)