> 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 Executar runbooks e consultar o respetivo estado usando a API do RealmJoins ## Visão geral O RealmJoin permite que você use Runbooks do Azure Automation para automatizar operações do dia a dia no seu ambiente. Veja [Runbooks](/pt/automatizacao/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 referência da API do RealmJoin](https://customer-api.realmjoin.com/scalar/v1) para ver quais operações são suportadas atualmente. As secções seguintes explicam como usar a API do RealmJoin para iniciar e acompanhar jobs de runbook. Pressupõe-se que você já tenha [ligado uma conta do Azure Automation](/pt/automatizacao/connecting-azure-automation.md) ao RealmJoin Portal. Além disso, certifique-se de [autenticar ](/pt/dev-reference/realmjoin-api/authentication.md)cada pedido à 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 aos runbooks. Quando você aciona a execução de um runbook, é criado um job para esse runbook e ele é colocado na fila para execução. Assim, em geral, um runbook não começa 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 para o script do runbook. Isto 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 utilizador. Cada job tem um estado que representa o seu estado atual de execução, veja [Microsoft Docs](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). Vamos focar-nos em `Queued`, `Running`, `Completed` e `Failed` neste documento. Tenha em atenção que isto é uma simplificação para facilitar a compreensão. ## Iniciar um job de runbook A API do RealmJoin oferece dois endpoints para acionar runbooks. `run` executará um runbook de forma síncrona e só terminará quando o runbook estiver realmente concluído ou falhado. Este endpoint devolve diretamente o estado de sucesso e a saída do job de runbook associado. `start` terá os mesmos parâmetros que `run` mas funciona de forma assíncrona. Irá devolver assim que um job de runbook estiver na fila. Irá devolver o `jobID` para permitir um fácil acompanhamento do novo job. ### Nomeação de runbooks Os runbooks são identificados pelo seu nome no Azure Automation. Em resumo: * Está sincronizado a partir do repositório GitHub do RealmJoin? Adicione `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` Veja [Convenções de nomeação](/pt/automatizacao/runbooks/naming-conventions.md) para mais detalhes. ### Exemplo Vamos assumir a seguinte situação: * Você tem as 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 início de sessão de um utilizador específico * Os parâmetros para o runbook (PowerShell) são: * `$UserName = "someone@contoso.com"` * `$Revoke = $true` Vamos usar o `run` endpoint para saber imediatamente se o job foi bem-sucedido. Vamos construir o **pedido**: Cabeçalhos: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Pedido / 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 } ``` O pedido demorará algum tempo, pois aguarda a execução do job. Certifique-se de ajustar o timeout dos seus clientes HTTP em conformidade. Caso contrário, tente usar o `start` endpoint, que irá devolver imediatamente. A resposta conterá o `jobID`, o `estado` (`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: Em execução na conta do Azure Automation", "streamType": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:27.96063+00:00", "summary": "getAutomationConnectionOrFromLocalCertificate: A obter a ligação de automação 'AzureRunAsConnection'", "streamType": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:31.560861+00:00", "summary": "Connect-RjRbAzureAD: A ligar com o módulo AzureAD: ...", "streamType": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:33.8860333+00:00", "summary": "## O acesso do utilizador someone@contoso.com foi revogado.", "streamType": "Output", "streamText": null, "value": null } ] } ``` Os streams de saída são separados em diferentes canais (`streamTypes`): `Output`, `Verbose`, `Error`. Isto permite filtrar erros ou reduzir a saída apenas às informações relevantes, mostrando apenas `Output`. Pode obter estes streams depois de um runbook terminar usando o `/runbook/jobs/{jobID}/output/streams` endpoint. (veja abaixo) ## Consultar o estado e a saída de um job Se um job já tiver sido criado, pode usar a API do RealmJoin para consultar o seu estado e a sua saída. ### Consultar o estado do job Use `/runbook/jobs/{jobID}/status` para consultar o estado atual. Veja [Autenticação ](/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho Authorization, 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 ``` Pedido / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/status ``` Este pedido não tem corpo. **Resposta** Status HTTP 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). ### Ler saída do job Use `/runbook/jobs/{jobID}/output/text` para obter uma representação simples em texto do conteúdo de saída de um runbook. Isto não incluirá o `Verbose` e `Error` stream. Veja [ler streams](#reading-specific-streams) para ler outros streams. [As exceções](#reading-exceptions) são tratadas separadamente. Veja [Autenticação ](/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho Authorization, 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 ``` Pedido / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/text ``` Este pedido não tem corpo. **Resposta** Status HTTP 200 (OK) Corpo (texto simples) ``` ## O grupo de distribuição 'Sales Team' foi criado. ``` ### Ler streams específicos Use `/runbook/jobs/{jobID}/output/streams` para obter uma representação JSON abrangente da saída de um runbook. Desta forma, pode aceder ao `Output`, `Verbose` e `Error` stream. [As exceções](#reading-exceptions) são tratadas separadamente. Veja [Autenticação ](/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho Authorization, o seguinte é apenas um exemplo. Assuma o `jobID` como sendo `1234545e-7a24-436a-90c9-6056b512345` **Pedido (todos os streams)** Cabeçalhos: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Pedido / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams ``` Este pedido 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": "A carregar o 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": "A carregar o 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: Em execução 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 verbosa 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": "Error", "streamText": null, "value": null } ] ``` Veja abaixo para ler mensagens de erro interruptivas e [exceções](#reading-exceptions) Para receber apenas um stream, por exemplo Verbose, pode adicionar um filtro ao pedido adicionando `?streamTypes=Verbose`. Também pode filtrar por `Output` e `Error`. **Pedido (filtrar por um único stream)** Cabeçalhos: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Pedido / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams?streamTypes=Verbose ``` Este pedido 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": "A carregar o 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": "A carregar o 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: Em execução na conta do Azure Automation", "streamType": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.8422225+00:00", "summary": "Mensagem verbosa ou de depuração", "streamType": "Verbose", "streamText": null, "value": null } ] ``` ### Ler exceções Use `/runbook/jobs/{jobID}/exception/text` para obter uma representação simples em texto da mensagem de exceção de um runbook (se existir). Isto não incluirá os `Output`, `Verbose` e `Error` streams. Veja [ler streams](#reading-specific-streams) para ler outros streams. As exceções são escritas quando ocorrem erros interruptivos na execução do script PowerShell associado ao runbook. Este endpoint apenas lê a mensagem em texto simples e não inclui detalhes técnicos, como em que linha de código o script parou. No nosso exemplo, um erro interruptivo foi causado por `throw "Exception"`. Veja [Autenticação ](/pt/dev-reference/realmjoin-api/authentication.md)sobre como criar um cabeçalho Authorization, 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 ``` Pedido / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/exception/text ``` Este pedido 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.