> 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 le permite usar Azure Automation Runbooks para automatizar las operaciones diarias en su entorno. Consulte [Runbooks](https://docs.realmjoin.com/es/automatizacion/runbooks.md) para obtener más información.

La API de RealmJoin le permite iniciar runbooks desde su aplicación, para consultar la ejecución correcta de ejecuciones previamente activadas. Consulte [la referencia de la API de RealmJoin](https://customer-api.realmjoin.com/scalar/v1) para ver qué operaciones están actualmente compatibles.

Las siguientes secciones explican cómo usar la API de RealmJoin para iniciar y realizar el seguimiento de trabajos de runbook. Se supone que ya ha [conectado una cuenta de Azure Automation](https://docs.realmjoin.com/es/automatizacion/connecting-azure-automation.md) al Portal de RealmJoin. Además, asegúrese de [autenticar ](https://docs.realmjoin.com/es/dev-reference/realmjoin-api/authentication.md)cada solicitud a la API de RealmJoin usando un encabezado HTTP Authorization adecuado.

## ¿Cómo maneja Azure Automation los runbooks?

Azure Automation tiene un enfoque de procesamiento por lotes con respecto a los runbooks. Cuando desencadena la ejecución de un runbook, se crea un trabajo para este runbook y se pone en cola para su ejecución.

En general, por tanto, un runbook no se iniciará de inmediato. Además, pueden existir varios trabajos para el mismo runbook al mismo tiempo en diferentes 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 agregue un alias de correo electrónico al buzón de un usuario.

Cada trabajo tiene un estado que representa su estado actual de ejecución, consulte [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 `Error` en este documento. Tenga en cuenta que esta es una simplificación con el propósito de facilitar la comprensión.

## Iniciando un trabajo de runbook

La API de RealmJoin ofrece dos puntos de conexión para desencadenar runbooks.

`run` ejecutará un runbook de forma sincrónica y solo devolverá/finalizará cuando el runbook haya terminado realmente o haya fallado. Este punto de conexión 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 asincrónica. Devolverá tan pronto como un trabajo de runbook esté en cola. Devolverá el `jobID` para permitir un fácil seguimiento del nuevo trabajo.

### Nomenclatura de runbooks

Los runbooks se identifican por su nombre en Azure Automation. En resumen:

* ¿Se sincroniza desde el repositorio GitHub de RealmJoin? Añada `rjgit-`como prefijo
* Ya sea `org_`, `device_`, `group_`, `user_` como ámbito (exactamente uno de esos)
* 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`

Consulta [Convenciones de nomenclatura](https://docs.realmjoin.com/es/automatizacion/runbooks/naming-conventions.md) para más detalles.

### Ejemplo

Supongamos la siguiente situación:

* Tiene sus credenciales de la API de RealmJoin y las ha codificado en `dC0xMjM0MTIzNDpteVMzY3JldCE=` (Base64)
* Quiere 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 para el runbook (PowerShell) son:
  * `$UserName = "someone@contoso.com"`
  * `$Revoke = $true`

Usaremos el `run` punto de conexión para saber de inmediato si el trabajo fue exitoso.

Construyamos el **solicitud**:

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úrese de adaptar en consecuencia el tiempo de espera de sus clientes HTTP. De lo contrario, pruebe a usar el `start` punto de conexión, que devolverá inmediatamente.

La respuesta contendrá el `jobID`, el `estado` (`Error` 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": "Completed",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Ejecutándose en la cuenta de Azure Automation",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Obteniendo la conexión de automatización 'AzureRunAsConnection'",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: Conectando con el módulo AzureAD: ...",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## Se ha revocado el acceso de usuario para someone@contoso.com.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}
```

Los flujos de salida se separan en diferentes canales (`streamTypes`): `Salida`, `Verbose`, `Error`. Esto permite filtrar errores o reducir la salida solo a información relevante mostrando solo `Salida`.

Puede obtener estos flujos después de que un runbook haya terminado usando el `/runbook/jobs/{jobID}/output/streams` punto de conexión. (véase más abajo)

## Consulta del estado y la salida de un trabajo

Si ya se ha creado un trabajo, puede usar la API de RealmJoin para consultar su estado y salida.

### Consulta del estado del trabajo

Utilice `/runbook/jobs/{jobID}/status` para consultar el estado actual.

Consulta [Autenticación ](https://docs.realmjoin.com/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de autorización, lo siguiente es solo un ejemplo.

Suponga que el `jobID` sea `1234545e-7a24-436a-90c9-6056b512345`

**`Solicitud`**

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 sin formato)

```
Completado
```

Otros posibles estados incluyen `Nuevo`, `Error`, `En ejecución`. Consulta [posibles estados de runbook](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses).

### Lectura de la salida del trabajo

Utilice `/runbook/jobs/{jobID}/output/text` para obtener una representación simple en texto sin formato de la salida de un runbook. Esto no incluirá el `Verbose` y `Error` flujo. Consulte [lectura de flujos](#reading-specific-streams) para leer otros flujos. [Excepciones](#reading-exceptions) se gestionan por separado.

Consulta [Autenticación ](https://docs.realmjoin.com/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de autorización, lo siguiente es solo un ejemplo.

Suponga que el `jobID` sea `1234545e-7a24-436a-90c9-6056b512345`

**Solicitud**

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 sin formato)

```
## Se ha creado el grupo de distribución 'Sales Team'.
```

### Lectura de flujos específicos

Utilice `/runbook/jobs/{jobID}/output/streams` para obtener una representación JSON completa de la salida de un runbook. De esta manera puede acceder al `Salida`, `Verbose` y `Error` flujo. [Excepciones](#reading-exceptions) se gestionan por separado.

Consulta [Autenticación ](https://docs.realmjoin.com/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de autorización, lo siguiente es solo un ejemplo.

Suponga 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": "Carga del módulo desde la ruta 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Carga del módulo desde la ruta '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: Ejecutándose en la cuenta de Azure Automation",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Salida normal",
        "streamType": "Output",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Mensaje detallado o de depuración",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Mensaje de error no interrumpido",
        "streamType": "Error",
        "streamText": null,
        "value": null
    }
]
```

Consulte a continuación para leer mensajes de error interrumpidos y [excepciones](#reading-exceptions)

Para recibir solo un único flujo, por ejemplo Verbose, puede agregar un filtro a la solicitud añadiendo `?streamTypes=Verbose`. También puede filtrar por `Salida` y `Error`.

**Solicitud (filtrar por un único 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": "Carga del módulo desde la ruta 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Carga del módulo desde la ruta '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: Ejecutándose en la cuenta de Azure Automation",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Mensaje detallado o de depuración",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]
```

### Lectura de excepciones

Utilice `/runbook/jobs/{jobID}/exception/text` para obtener una representación simple en texto sin formato del mensaje de excepción de un runbook (si existe). Esto no incluirá los `Salida`, `Verbose` y `Error` flujos. Consulte [lectura de flujos](#reading-specific-streams) para leer otros flujos.

Las excepciones se escriben cuando se producen errores interrumpidos en la ejecución del script de PowerShell asociado con el runbook. Este punto de conexión solo leerá el mensaje en texto sin formato y no incluye detalles técnicos, como en qué línea de código se detuvo el script.

En nuestro ejemplo, un error interrumpido fue causado por `throw "Exception"`.

Consulta [Autenticación ](https://docs.realmjoin.com/es/dev-reference/realmjoin-api/authentication.md)sobre cómo crear un encabezado de autorización, lo siguiente es solo un ejemplo.

Suponga que el `jobID` sea `1234545e-7a24-436a-90c9-6056b512345`

**Solicitud**

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 sin formato)

```
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=<question>&goal=<user_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.
