Interagindo com Runbooks

Execute runbooks e consulte seu status usando a API do RealmJoin

Visão Geral

O RealmJoin permite que você use Runbooks do Azure Automation para automatizar operações do dia a dia em seu ambiente. Veja Runbooks para mais informações.

A API do RealmJoin permite que você inicie runbooks a partir do seu aplicativo, para consultar a execução bem-sucedida de execuções previamente acionadas. Veja a descrição Swagger do RealmJoin para ver quais operações estão atualmente suportadas.

As seções a seguir descrevem como usar a API do RealmJoin para iniciar e rastrear jobs de runbook. Pressupõe-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 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 enfileirado para execução.

Portanto, em geral, um runbook não iniciará imediatamente. Além disso, múltiplos 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 ser, por exemplo, duas variáveis como $username quanto para $newEmailAddress se o runbook for destinado a 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. Nós vamos nos concentrar em Enfileirado, Em execução, Concluído quanto para Falhou neste documento. Esteja ciente de que isto é uma simplificação para fins de entendimento mais fácil.

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 aceitará os mesmos parâmetros que run mas funciona de maneira assíncrona. Ele retornará assim que um job de runbook for enfileirado. Ele retornará o jobID para possibilitar o rastreamento fácil do novo job.

Nomeação de Runbooks

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

• Está sincronizado do repositório do RealmJoin no GitHub? Adicione prefixo rjgit-como prefixo

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

• Uma categoria, como general_negação 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 Nomeação para mais detalhes.

Exemplo

Vamos assumir a seguinte situação:

• Você possui 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 para um usuário específico

• Os parâmetros para o runbook (PowerShell) são:

  • $UserName = "[email protected]"

  • $Revoke = $true

Usaremos o endpoint run 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": "[email protected]", 
   "Revoke": true 
}

A solicitação levará algum tempo, pois aguarda a execução do job. Por favor, certifique-se de ajustar o timeout do seu cliente HTTP adequadamente. Caso contrário, tente usar o endpoint start que retornará imediatamente.

A resposta conterá o jobID, o status (Falhou negação Concluído) 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": "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 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": "## Acesso do usuário [email protected] foi revogado.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}

Os fluxos de saída são separados em diferentes canais (streamTypes): Output, Verbose, Error. Isso permite filtrar por erros ou reduzir a saída apenas para informações relevantes ao mostrar somente Output.

Você pode obter esses fluxos após um runbook ser finalizado usando o endpoint /runbook/jobs/{jobID}/output/streams (veja abaixo)

Consultando o status e a saída de um Job

Se um job já foi 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 sobre como criar um cabeçalho de Authorization, o seguinte é apenas um exemplo.

Assuma o jobID para ser 1234545e-7a24-436a-90c9-6056b512345

Solicitação

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. Veja possíveis estados 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. Isto não incluirá o Verbose quanto para Error fluxo. Veja lendo fluxos para ler outros fluxos. Exceções são tratados separadamente.

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

Assuma o jobID para ser 1234545e-7a24-436a-90c9-6056b512345

Solicitação

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)

## 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. Desta forma você pode acessar o Output, Verbose quanto para Error fluxo. Exceções são tratados separadamente.

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

Assuma o jobID para ser 1234545e-7a24-436a-90c9-6056b512345

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

Status HTTP 200 (OK)

Corpo (JSON, array 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 Debug",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Mensagem de Erro não interrompente",
        "streamType": "Error",
        "streamText": null,
        "value": null
    }
]

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

Para receber apenas um único fluxo, por exemplo Verbose, você pode adicionar um filtro à requisição adicionando ?streamTypes=Verbose. Você também pode filtrar por Output quanto para Error.

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

Status HTTP 200 (OK)

Corpo (JSON, array 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 em texto simples da mensagem de exceção de um runbook (se presente). Isto não incluirá os Output, Verbose quanto para Error fluxos. Veja lendo fluxos para ler outros fluxos.

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

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

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

Assuma o jobID para ser 1234545e-7a24-436a-90c9-6056b512345

Solicitação

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)

Exception (Exception)