# Interagindo com Runbooks ## Overview RealmJoin permite que você use Azure Automation Runbooks para automatizar as operações diárias em seu ambiente. Veja [Runbooks](/pt/automacao/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 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](/pt/automacao/connecting-azure-automation.md) ao Portal do RealmJoin. Além disso, certifique-se de [autenticar ](/pt/dev-reference/realmjoin-api/authentication.md)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](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). 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](/pt/automacao/runbooks/naming-conventions.md) 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 = "someone@contoso.com"` * `$Revoke = $true` Usaremos o `run` endpoint para saber imediatamente se o trabalho foi bem-sucedido. Vamos construir o **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 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): ```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 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 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 ](/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` **`Pedido`** 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** 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 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](#reading-specific-streams) para ler outros fluxos. [Exceções](#reading-exceptions) são tratados separadamente. Ver [Autenticação ](/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` **Pedido** 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** 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. Ver [Autenticação ](/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** Http Status 200 (OK) Corpo (JSON, matriz 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 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](#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 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** Http Status 200 (OK) Corpo (JSON, matriz 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 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](#reading-specific-streams) 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 ](/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` **Pedido** 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** Http Status 200 (OK) Corpo (Texto simples) ``` Exceção (Exceção) ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.realmjoin.com/pt/dev-reference/interacting-with-runbooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.