Interacción con runbooks

Ejecute runbooks y consulte su estado usando la API de RealmJoin

pestaña Resumen

RealmJoin te permite usar Runbooks de Azure Automation para automatizar las operaciones diarias en tu entorno. Ver Runbooks para más información.

La API de RealmJoin te permite iniciar runbooks desde tu aplicación y consultar la ejecución exitosa de ejecuciones previamente activadas. Ver la descripción Swagger de RealmJoin para ver qué operaciones están actualmente soportadas.

Las siguientes secciones explican cómo usar la API de RealmJoin para iniciar y rastrear trabajos de runbook. Se asume que ya tienes conectada una cuenta de Azure Automation al Portal de RealmJoin. Además, asegúrate de autenticarse en cada solicitud contra la API de RealmJoin usando un encabezado http Authorization apropiado.

¿Cómo maneja 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 ese runbook y se pone en cola para su ejecución.

Así que, en general, un runbook no comenzará inmediatamente. Además pueden existir múltiples 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 como $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 actual de ejecución, ver Microsoft Docs. Nos centraremos en En cola, En ejecución, Completado como Fallido en este documento. Ten en cuenta que esto es una simplificación con el fin de facilitar la comprensión.

Iniciar 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 esté realmente completado o haya fallado. Este endpoint devuelve directamente el estado de éxito y la salida del trabajo de runbook asociado.

start tomará 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 permitir un seguimiento sencillo del nuevo trabajo.

Nomenclatura de Runbooks

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

• ¿Se sincroniza desde el repositorio de GitHub de RealmJoin? Añade prefijo 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

Vea Convenciones de Nombres para más detalles.

Ejemplo

Supongamos la siguiente situación:

• Usted tiene sus credenciales de la API de RealmJoin y las codificó a 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 para el runbook (PowerShell) son:

  • $UserName = "[email protected]"

  • $Revoke = $true

Usaremos el run endpoint para saber inmediatamente si el trabajo fue exitoso.

Construyamos los solicitud:

Encabezados:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Solicitud / URI:

POST https://customer-api.realmjoin.com/runbook/rjgit-user_security_revoke-or-restore-access/run

Cuerpo (en notación JSON):

{ 
   "UserName": "[email protected]", 
   "Revoke": true 
}

La solicitud tomará un tiempo, ya que espera a que el trabajo se ejecute. Por favor asegúrate de adaptar el tiempo de espera (timeout) de tu cliente HTTP en consecuencia. De lo contrario, intenta usar el start endpoint, que devolverá inmediatamente.

La respuesta contendrá el jobIDdurante el despliegue inicial estado (Fallido o Completado) y todos los flujos de salida del runbook.

Respuesta:

Estado Http: 200 (OK)

Cuerpo (en notación JSON):

{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Completed",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Ejecutando 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": "## El acceso de usuario para [email protected] ha sido revocado.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}

Los flujos de salida están separados en diferentes canales (streamTypes): Salida, Detallado, 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 más abajo)

Consulta del estado y salida de un trabajo

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

Consulta del estado del trabajo

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

Vea Autenticación sobre cómo crear un encabezado de Autorización, lo siguiente es solo un ejemplo.

Supón el jobID sea 1234545e-7a24-436a-90c9-6056b512345

Solicitud

Encabezados:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Solicitud / URI:

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 estados posibles incluyen Nuevo, Fallido, En ejecución. Ver posibles estados de Runbook.

Lectura de la salida del trabajo

Usa /runbook/jobs/{jobID}/output/text para obtener una representación simple en texto plano de la salida de un runbook. Esto no incluirá el Detallado como Error flujo. Ver lectura de flujos para leer otros flujos. Excepciones se manejan por separado.

Vea Autenticación sobre cómo crear un encabezado de Autorización, lo siguiente es solo un ejemplo.

Supón el jobID sea 1234545e-7a24-436a-90c9-6056b512345

Solicitud

Encabezados:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Solicitud / URI:

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 'Equipo de Ventas' ha sido creado.

Lectura de flujos específicos

Usa /runbook/jobs/{jobID}/output/streams para obtener una representación JSON completa de la salida de un runbook. De esta manera puedes acceder al Salida, Detallado como Error flujo. Excepciones se manejan por separado.

Vea Autenticación sobre cómo crear un encabezado de Autorización, lo siguiente es solo un ejemplo.

Supón el jobID sea 1234545e-7a24-436a-90c9-6056b512345

Solicitud (todos los flujos)

Encabezados:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Solicitud / URI:

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, arreglo de mensajes)

[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Cargando 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": "Cargando 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: Ejecutando en la cuenta de Azure Automation",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Salida regular",
        "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 interrumpible",
        "streamType": "Error",
        "streamText": null,
        "value": null
    }
]

Ver más abajo para leer mensajes de error interrumpibles y excepciones

Para recibir solo un flujo, por ejemplo Detallado, puedes añadir un filtro a la solicitud agregando ?streamTypes=Verbose. También puedes filtrar por Salida como Error.

Solicitud (filtrar por un solo flujo)

Encabezados:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Solicitud / URI:

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, arreglo de mensajes)

[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Cargando 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": "Cargando 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: Ejecutando 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

Usa /runbook/jobs/{jobID}/exception/text para obtener una representación simple en texto plano del mensaje de excepción de un runbook (si está presente). Esto no incluirá los Salida, Detallado como Error flujos. Ver lectura de flujos para leer otros flujos.

Las excepciones se escriben cuando ocurren errores interrumpibles en la ejecución del script PowerShell asociado con el 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 "Exception".

Vea Autenticación sobre cómo crear un encabezado de Autorización, lo siguiente es solo un ejemplo.

Supón el jobID sea 1234545e-7a24-436a-90c9-6056b512345

Solicitud

Encabezados:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Solicitud / URI:

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)

Exception (Exception)