> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/dev-reference/interacting-with-runbooks.md). # Interagir com runbooks ## Visão geral RealmJoin permite usar Runbooks do Azure Automation para automatizar as operações do dia a dia no seu ambiente. Veja [Runbooks](/pt/automacao/runbooks.md) 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](https://customer-api.realmjoin.com/swagger/index.html) 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](/pt/automacao/connecting-azure-automation.md) ao Portal 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 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](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). 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](/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ê 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 = "someone@contoso.com"` * `$Revoke = $true` Usaremos o `run` endpoint para saber imediatamente se o job foi bem-sucedido. Vamos construir o **solicitar**: 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 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): ```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 someone@contoso.com 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 ](/pt/dev-reference/realmjoin-api/authentication.md)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: ```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** 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](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 simples da saída de um runbook. Isso não incluirá o `Verbose` e `Error` stream. Veja [leitura de streams](#reading-specific-streams) para ler outros streams. [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. Assuma o `jobID` como sendo `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** 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](#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. Assuma o `jobID` como sendo `1234545e-7a24-436a-90c9-6056b512345` **Solicitação (todos os streams)** 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** Status HTTP 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 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](#reading-exceptions) 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: ```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** Status HTTP 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 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](#reading-specific-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 ](/pt/dev-reference/realmjoin-api/authentication.md)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: ```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** Status HTTP 200 (OK) Corpo (texto simples) ``` Exceção (Exception) ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.realmjoin.com/pt/dev-reference/interacting-with-runbooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.