> 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/es/dev-reference/interacting-with-runbooks.md). # Interacción con Runbooks Ejecuta runbooks y consulta su estado mediante la API de RealmJoin ## Resumen RealmJoin te permite usar Azure Automation Runbooks para automatizar las operaciones del día a día en tu entorno. Consulta [Runbooks](/es/automatizacion/runbooks.md) para más información. La API de RealmJoin te permite iniciar runbooks desde tu aplicación, para consultar la ejecución exitosa de ejecuciones desencadenadas previamente. Consulta [la referencia de la API de RealmJoin](https://customer-api.realmjoin.com/scalar/v1) para ver qué operaciones son compatibles actualmente. Las siguientes secciones explican cómo usar la API de RealmJoin para iniciar y seguir trabajos de runbook. Se supone que ya tienes [conectada una cuenta de Azure Automation](/es/automatizacion/connecting-azure-automation.md) a RealmJoin Portal. Además, asegúrate de [autenticar ](/es/dev-reference/realmjoin-api/authentication.md)cada solicitud contra la API de RealmJoin usando un encabezado HTTP Authorization adecuado. ## ¿Cómo gestiona Azure Automation los runbooks? Azure Automation tiene un enfoque de procesamiento por lotes respecto a los runbooks. Cuando activas la ejecución de un runbook, se crea un trabajo para este runbook y se pone en cola para su ejecución. En general, un runbook no se iniciará inmediatamente. Además, pueden existir varios trabajos del mismo runbook al mismo tiempo en distintos estados de ejecución. Cada trabajo tiene un conjunto de parámetros (entradas) que se pasan al script del runbook. Esto puede ser, por ejemplo, dos variables como `$username` y `$newEmailAddress` si se supone que el runbook debe agregar un alias de correo electrónico al buzón de un usuario. Cada trabajo tiene un estado que representa su estado de ejecución actual; consulta [Microsoft Docs](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). Nos centraremos en `En cola`, `En ejecución`, `Completado` y `Fallido` en este documento. Ten en cuenta que esto es una simplificación para facilitar la comprensión. ## Inicio de un trabajo de runbook La API de RealmJoin ofrece dos endpoints para activar runbooks. `run` ejecutará un runbook de forma síncrona y solo devolverá/finalizará cuando el runbook se haya completado realmente o haya fallado. Este endpoint devuelve directamente el estado de éxito y la salida del trabajo de runbook asociado. `start` tendrá los mismos parámetros que `run` pero funciona de forma asíncrona. Devolverá tan pronto como un trabajo de runbook esté en cola. Devolverá el `jobID` para facilitar el seguimiento del nuevo trabajo. ### Nomenclatura de runbooks Los runbooks se identifican por su nombre en Azure Automation. En resumen: * ¿Está sincronizado desde el repositorio GitHub de RealmJoin? Añade `rjgit-`como prefijo * Ya sea `org_`, `device_`, `group_`, `user_` como ámbito (exactamente uno de ellos) * Una categoría, como `general_`o `security_` * El nombre del runbook, separado por `_` como `add-xyz-exception` El resultado en este caso sería: `rjgit-org_security_add-xyz-exception` Ver [Convenciones de nomenclatura](/es/automatizacion/runbooks/naming-conventions.md) para más detalles. ### Ejemplo Supongamos la siguiente situación: * Tienes tus credenciales de la API de RealmJoin y las has codificado en `dC0xMjM0MTIzNDpteVMzY3JldCE=` (Base64) * Quieres iniciar el runbook `rjgit-user_security_revoke-or-restore-access` para bloquear el inicio de sesión de un usuario específico * Los parámetros del runbook (PowerShell) son: * `$UserName = "someone@contoso.com"` * `$Revoke = $true` Usaremos el `run` endpoint para saber de inmediato si el trabajo se completó correctamente. Construyamos la **solicitar**: Encabezados: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Solicitud / URI: ```http POST https://customer-api.realmjoin.com/runbook/rjgit-user_security_revoke-or-restore-access/run ``` Cuerpo (en notación JSON): ```json { "UserName": "someone@contoso.com", "Revoke": true } ``` La solicitud tardará un poco, ya que espera a que se ejecute el trabajo. Asegúrate de adaptar el tiempo de espera de tus clientes HTTP en consecuencia. Si no, intenta usar el `start` endpoint, que devolverá el resultado inmediatamente. La respuesta contendrá el `jobID`, el `estado` (`Fallido` o `Completado`) y todos los flujos de salida del runbook. **Respuesta**: Estado HTTP: `200` (OK) Cuerpo (en notación JSON): ```json { "jobID": "1234545e-7a24-436a-90c9-6056b512345", "status": "Completado", "streams": [ { "time": "2021-12-15T14:47:27.7756185+00:00", "summary": "RealmJoin.RunbookHelper: Ejecutándose en la cuenta de Azure Automation", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:27.96063+00:00", "summary": "getAutomationConnectionOrFromLocalCertificate: Obteniendo la conexión de automatización 'AzureRunAsConnection'", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:31.560861+00:00", "summary": "Connect-RjRbAzureAD: Conectándose con el módulo AzureAD: ...", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:33.8860333+00:00", "summary": "## El acceso de usuario para someone@contoso.com ha sido revocado.", "streamType": "Salida", "streamText": null, "value": null } ] } ``` Los flujos de salida se separan en distintos canales (`streamTypes`): `Salida`, `Verbose`, `Error`. Esto permite filtrar errores o reducir la salida solo a la información relevante mostrando únicamente `Salida`. Puedes obtener estos flujos después de que un runbook haya finalizado usando el `/runbook/jobs/{jobID}/output/streams` endpoint. (ver abajo) ## Consulta del estado y la salida de un trabajo Si un trabajo ya se ha creado, puedes usar la API de RealmJoin para consultar su estado y salida. ### Consulta del estado del trabajo Use `/runbook/jobs/{jobID}/status` para consultar el estado actual. Ver [Autenticación ](/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de Authorization, lo siguiente es solo un ejemplo. Supón que el `jobID` sea `1234545e-7a24-436a-90c9-6056b512345` **`Solicitar`** Encabezados: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Solicitud / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/status ``` Esta solicitud no tiene cuerpo. **Respuesta** Estado HTTP 200 (OK) Cuerpo (texto plano) ``` Completado ``` Otros posibles estados incluyen `Nuevo`, `Fallido`, `En ejecución`. Consulte [posibles estados del runbook](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). ### Lectura de la salida del trabajo Use `/runbook/jobs/{jobID}/output/text` para obtener una representación sencilla en texto plano de la salida de un runbook. Esto no incluirá el `Verbose` y `Error` flujo. Consulta [la lectura de flujos](#reading-specific-streams) para leer otros flujos. [Excepciones](#reading-exceptions) se manejan por separado. Ver [Autenticación ](/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de Authorization, lo siguiente es solo un ejemplo. Supón que el `jobID` sea `1234545e-7a24-436a-90c9-6056b512345` **Solicitar** Encabezados: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Solicitud / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/text ``` Esta solicitud no tiene cuerpo. **Respuesta** Estado HTTP 200 (OK) Cuerpo (texto plano) ``` ## El grupo de distribución 'Sales Team' ha sido creado. ``` ### Lectura de flujos específicos Use `/runbook/jobs/{jobID}/output/streams` para obtener una representación JSON completa de la salida de un runbook. De este modo puedes acceder al `Salida`, `Verbose` y `Error` flujo. [Excepciones](#reading-exceptions) se manejan por separado. Ver [Autenticación ](/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de Authorization, lo siguiente es solo un ejemplo. Supón que el `jobID` sea `1234545e-7a24-436a-90c9-6056b512345` **Solicitud (todos los flujos)** Encabezados: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Solicitud / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams ``` Esta solicitud no tiene cuerpo. **Respuesta** Estado HTTP 200 (OK) Cuerpo (JSON, matriz de mensajes) ```json [ { "time": "2021-12-20T08:37:46.8572747+00:00", "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:46.9272241+00:00", "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.1522235+00:00", "summary": "RealmJoin.RunbookHelper: Ejecutándose en la cuenta de Azure Automation", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.3122219+00:00", "summary": "Salida normal", "streamType": "Salida", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.8422225+00:00", "summary": "Mensaje detallado o de depuración", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.7672223+00:00", "summary": "Mensaje de error no interrumpible", "streamType": "Error", "streamText": null, "value": null } ] ``` Consulta abajo para leer mensajes de error interrumpibles y [excepciones](#reading-exceptions) Para recibir solo un flujo, por ejemplo Verbose, puedes agregar un filtro a la solicitud añadiendo `?streamTypes=Verbose`. También puedes filtrar por `Salida` y `Error`. **Solicitud (filtrar para un solo flujo)** Encabezados: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Solicitud / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams?streamTypes=Verbose ``` Esta solicitud no tiene cuerpo. **Respuesta** Estado HTTP 200 (OK) Cuerpo (JSON, matriz de mensajes) ```json [ { "time": "2021-12-20T08:37:46.8572747+00:00", "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:46.9272241+00:00", "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.1522235+00:00", "summary": "RealmJoin.RunbookHelper: Ejecutándose en la cuenta de Azure Automation", "streamType": "Detallado", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.8422225+00:00", "summary": "Mensaje detallado o de depuración", "streamType": "Detallado", "streamText": null, "value": null } ] ``` ### Lectura de excepciones Use `/runbook/jobs/{jobID}/exception/text` para obtener una representación sencilla en texto plano del mensaje de excepción de un runbook (si existe). Esto no incluirá los `Salida`, `Verbose` y `Error` flujos. Consulta [la lectura de flujos](#reading-specific-streams) para leer otros flujos. Las excepciones se escriben cuando se producen errores interrumpibles en la ejecución del script de PowerShell asociado al runbook. Este endpoint solo leerá el mensaje en texto plano y no incluye detalles técnicos, como en qué línea de código se detuvo el script. En nuestro ejemplo, un error interrumpible fue causado por `throw "Excepción"`. Ver [Autenticación ](/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de Authorization, lo siguiente es solo un ejemplo. Supón que el `jobID` sea `1234545e-7a24-436a-90c9-6056b512345` **Solicitar** Encabezados: ```http Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE= Content-Type: application/json ``` Solicitud / URI: ```html GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/exception/text ``` Esta solicitud no tiene cuerpo. **Respuesta** Estado HTTP 200 (OK) Cuerpo (texto plano) ``` Excepción (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/es/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.