Interacción con runbooks

Ejecuta runbooks y consulta su estado mediante la API de RealmJoin

Descripción general

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

La API de RealmJoin te permite iniciar runbooks desde tu aplicación y consultar la ejecución correcta de ejecuciones desencadenadas previamente. Consulta la descripción de Swagger de RealmJoin para ver qué operaciones están admitidas actualmente.

Las siguientes secciones explican cómo usar la API de RealmJoin para iniciar y hacer seguimiento de trabajos de runbook. Se supone que ya has conectado una cuenta de Azure Automation a RealmJoin Portal. Además, asegúrate de autenticar cada solicitud contra la API de RealmJoin mediante un encabezado HTTP de autorización apropiado.

¿Cómo maneja Azure Automation los runbooks?

Azure Automation tiene un enfoque de procesamiento por lotes con 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 se iniciará de inmediato. 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 actual de ejecución; consulta Microsoft Docs. Nos centraremos en En cola, En ejecución, Completado y Error en este documento. Ten en cuenta que esto es una simplificación para 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 sincrónica 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 tomará los mismos parámetros que run pero funciona de forma asíncrona. Devolverá la respuesta en cuanto un trabajo de runbook quede 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:

• ¿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 nomenclatura 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)
• 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 = "[e-mail]"
  • $Revoke = $true

Usaremos el run endpoint para saber de inmediato si el trabajo tuvo éxito.

Construyamos el solicitar:

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": "[e-mail]", 
   "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 tu cliente HTTP en consecuencia. De lo contrario, prueba a usar el start endpoint, que devolverá la respuesta de inmediato.

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):

{
    "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: Conectando con el módulo AzureAD: ...",
            "streamType": "Detallado",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## El acceso del usuario [e-mail] ha sido revocado.",
            "streamType": "Salida",
            "streamText": null,
            "value": null
        }
    ]
}

Los flujos de salida se separan en distintos canales (streamTypes): Salida, Detallado, ErrorEsto permite filtrar los errores o reducir la salida solo a la información relevante mostrando únicamente Salida.

Puedes obtener estos flujos después de que termine un runbook usando el /runbook/jobs/{jobID}/output/streams endpoint. (consulta abajo)

Consultar el 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.

Consultar el estado del trabajo

Use /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 que el jobID es 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, Error, En ejecución. Véase posibles estados del runbook.

Leer la salida del trabajo

Use /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 y Error flujo. Consulta 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 que el jobID es 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)

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

Leer flujos específicos

Use /runbook/jobs/{jobID}/output/streams para obtener una representación JSON completa de la salida de un runbook. De esta forma puedes acceder al Salida, Detallado y 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 que el jobID es 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, matriz 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": "Detallado",
        "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": "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 interruptivo",
        "streamType": "Error",
        "streamText": null,
        "value": null
    }
]

Consulta abajo para leer los mensajes de error que interrumpen la ejecución 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 y Error.

Solicitud (filtrar para 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, matriz 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": "Detallado",
        "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": "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
    }
]

Leer excepciones

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

Las excepciones se escriben cuando se producen errores que interrumpen la ejecución del script de 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 que interrumpió la ejecución 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 que el jobID es 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)

Excepción (Exception)