Personalización de runbooks
Adapte los runbooks genéricos de RealmJoin a las necesidades de sus entornos.
pestaña Resumen
La implementación del runbook RealmJoin ofrece capacidades de personalización al autor de un runbook o al administrador de un entorno, para que puedan:
Alojar parámetros y plantillas específicos del cliente/inquilino
Ofrecer elementos de IU como selectores de usuario o selecciones desplegables
Presentar explicaciones legibles por humanos de los parámetros
Ocultar elementos de IU innecesarios
Las personalizaciones pueden incluirse en el runbook mismo y/o almacenarse en la instancia del Portal RealmJoin del cliente. Por defecto, intentaremos ofrecer valores predeterminados sensatos en los runbooks ofrecidos en GitHub.
Algunos runbooks vendrán con ejemplos de cómo configurar plantillas específicas del cliente, como especificar ubicaciones de oficinas para la incorporación de usuarios.
Formatear
La personalización puede definirse (en orden descendente de prioridad)
Bloque de JSON en configuración del Portal RealmJoin, anulando el comportamiento predeterminado del runbook
Bloque de JSON en el encabezado de un runbook
Adicionalmente (con la prioridad más baja)
por parámetro en el encabezado del runbook
por parámetro en el bloque param del runbook (usando el Módulo de Ayuda RJRb)
Algunas funcionalidades (como las plantillas) están disponibles solo en formato JSON. Algunas funcionalidades (como crear un selector de usuario) están disponibles solo especificando un tipo de dato en el bloque param. Puede combinar varios tipos de personalizaciones para obtener mejores resultados.
Bloque Param del Runbook
El Portal RealmJoin analiza el bloque param de PowerShell de un runbook para determinar qué campos de entrada renderizar. Cuando es posible, también validará las entradas según el tipo .NET dado para una variable.
Los siguientes tipos de datos se entienden actualmente:
[bool],[boolean]- presentará un interruptor binario[string]- presentará un cuadro de texto para escribir cualquier entrada alfanumérica[int]- presentará un cuadro de texto, permitiendo solo entradas numéricas[DateTime],[DateTimeOffset]- Presentará un selector de fecha/hora
Puede aplicar modificadores estándar de PowerShell a los parámetros. El Portal RealmJoin, en particular, entenderá si especifica [Parameter(Mandatory = $true)] para indicar un parámetro obligatorio y hacer cumplir que dichos parámetros se completen.
Cuando sea posible, el Portal RealmJoin también leerá y presentará valores predeterminados dados en la IU.
Tenga en cuenta que los valores predeterminados del runbook pueden ser anulados por las personalizaciones. Adicionalmente, los parámetros pueden ocultarse completamente mediante personalizaciones.
Personalización de Parámetros
Para poder personalizar parámetros, asegúrese de incluir el Módulo PS Runbook Helper de RealmJoin en su runbook:
#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }
Luego puede incluir [ValidateScript( { Use-RJInterface ... } )] declaraciones en las definiciones de parámetros. Por ejemplo, lo siguiente creará un selector de usuario, permitiendo elegir un usuario de Entra ID y pasará su id de objeto como cadena al runbook.
Analicemos esto parte por parte. [ValidateScript...] es un modificador para el siguiente parámetro definido en el bloque param. En este caso la variable $AssignedUserId.
Use-RJInterface es parte de nuestro Módulo de Ayuda de Runbook RealmJoin PowerShell. Le permite especificar qué tipo de entrada espera usando -Type como -Entity, si eso no está ya totalmente definido por el tipo de variable.
-DisplayName le permite pasar un aviso/descripcion legible por humanos para este parámetro al Portal RealmJoin.
Recursos de Graph
En el ejemplo anterior, la fuente de información es MS Graph, como se describe por -Type Graph. Para MS Graph, use -Entity para especificar qué tipo de recurso espera. Las entidades disponibles son deseada y un, Grupo, Dispositivo. Esto producirá un selector para usuarios, grupos o dispositivos en el Entra ID dado.
El selector incluye una búsqueda rápida, para localizar fácilmente el recurso requerido.
Actualmente, no es posible la selección múltiple usando un selector.
Por defecto, un selector de MS Graph devolverá el ID del objeto. Si necesita, por ejemplo, el nombre principal del usuario (UPN) en su lugar, asegúrese de incluir "name" como sufijo en el nombre de su variable. Entonces, básicamente, para obtener el id de un usuario, nombre el parámetro $userid. Si quiere un UPN, nómbrelo $username.
Filtrado de Graph
Si está usando un selector basado en MS Graph, también puede especificar -Filter y usar un Filtro ODATA para limitar los objetos ofrecidos en el selector.
El siguiente ejemplo listará solo grupos del Entra ID que comiencen con "LIC_".
Puede preparar filtros y reutilizarlos en múltiples scripts usando el almacén de datos central. En este caso, solo haga referencia al filtro por nombre usando -Filter "ref:LicenseGroup", donde ref: indica buscar un filtro almacenado.
Este ejemplo específico ref:LicenseGroup está disponible por defecto sin configuración adicional.
Encabezado del Runbook
El Portal puede analizar la ayuda basada en comentarios del runbook, si está presente.
Aquí hay un ejemplo:
.SYNOPSIS - Dé una descripción muy breve de la función de su runbook. Esto se mostrará en la lista de runbooks disponibles.
.DESCRIPTION - Dé una descripción de la función de su runbook. Puede contener algo más de detalle, ya que esto se mostrará dentro del cuadro de diálogo de ejecución/parametros del runbook.
.PARAMETER - Debe ir seguido del nombre de un parámetro. Le permite dar una explicación detallada de la entrada esperada para el parámetro en cuestión.
.INPUTS - Puede contener un bloque de personalización de Runbook basado en JSON.
.NOTES - No se analiza/renderiza. Por favor use este espacio para escribir qué permisos y requisitos existen para su runbook.
.EXAMPLE - No se analiza/renderiza. Puede contener un ejemplo de una personalización basada en JSON para usar en el almacén de datos de RealmJoin en su inquilino. Estos pueden ser ejemplos de cómo crear plantillas, p. ej. para diferentes flujos de trabajo o clases de usuario.
Personalización basada en JSON
Almacén de datos central
Cada inquilino de Azure puede alojar un almacén de datos "Runbook Customizations", que se encuentra en https://portal.realmjoin.com/settings/runbooks-customizations .
El formato es JSON con comentarios, permitiendo comas finales. Actualmente, hay tres secciones relevantes, Configuración, Plantillas, Runbooks.
Sección Runbooks
Runbooks es analizada por el portal al iniciar un runbook. Si existe una sección nombrada como el Runbook de Azure Automation actual, su contenido se usará para personalizar el frontend mostrado al usuario.
Suponga el siguiente runbook de demostración simple, llamado rjgit-device_demo-runbook-customizing.
Si no se personaliza, se presentará así en el frontend:
Reflexiones:
Como este runbook se inicia desde el contexto de un dispositivo en el portal, el
$DeviceIdes información redundante para un usuario. Ya sé en qué dispositivo estoy trabajando.¿Qué pasa si activo o desactivo el "Extra Workflow"? ¿Necesito pensar en "Extra Workflow Time" si desactivo "Extra Workflow"?
Mejorémoslo. El siguiente JSON de ejemplo en el almacén de datos central modificará la IU para el runbook.
Puede usar la misma notación/características en su encabezado del runbook.
ParameterList
Cada parámetro tiene su propia sección en ParameterList. Modificadores permiten cambiar el comportamiento de ese parámetro.
El resultado se verá así:
Elegir el flujo de trabajo adicional presentará (mostrará) más parámetros:
Esto muestra menos desorden en comparación con antes de aplicar la personalización. Al mismo tiempo, hay más información sobre las alternativas de "Extra Workflow" disponible para el usuario. Además, un usuario solo se preocupará por "Extra Workflow Time" si es relevante.
Cambiar la visibilidad de ese campo se realizó usando un "Customization" bloque dentro de una de las "Select" opciones. Actualmente puede tener como máximo un tal "Customization" bloque activo a la vez.
Como puede ver, el parámetro $DeviceId está completamente oculto. Esto se hace estableciendo el "Hide": true para este parámetro.
Los parámetros pueden tener un DisplayName. Ofrecimos un texto amigable para humanos DisplayName para reemplazar $ExtraWorkflowTime en la IU. Vea otros modificadores para más información.
Puede insertar parámetros "sin nombre" (que faltan la Nombre declaración) como la sección "Ejecutar flujo de trabajo extra", si desea ofrecer elementos de IU sin devolver directamente un valor. Esto normalmente solo se usa en conjunto con Selecciona.
Selecciona
Usamos Selecciona, para mostrar una lista de Opciones en un desplegable. Cada opción puede Mostrar texto, o activar un Personalización, como establecer Hide o un Default valor en otros parámetros. En nuestro ejemplo, lo usamos para (des)ocultar $ExtraWorkflowTime y anular $ExtraWorkflowel valor de 's.
$ExtraWorkflowTime se muestra así solo cuando es relevante y el interruptor binario $ExtraWorkflow ahora se reemplaza por alternativas significativas desde la perspectiva del usuario.
En caso de un Selecciona para un parámetro nombrado, cada opción debe tener un "ParameterValue": "..." para pasar al runbook. Puede colocar un "ShowValue: false" dentro del Selecciona bloque para mostrar solo el desplegable y no un campo para el valor resultante del parámetro.
Ejemplo de parámetro nombrado:
debe tener un buzón conectado, para que podamos notificarle en caso de que haya problemas relevantes con RealmJoin. Si desea cambiarlo, por favor Default / DefaultValue la declaración en el parámetro también especifica el estado inicial del desplegable. En caso de un parámetro sin nombre, use el DisplayName del opción deseada, de lo contrario dé un valor de retorno predeterminado, como "true" o "false" o alguna cadena.
Parámetros
Si solo tiene parámetros nombrados, puede usar el formato ligeramente más corto Parámetros en lugar de ParameterList.
Para un ejemplo vea SelectSimple
SelectSimple
Si no se necesita el pleno poder de un Selecciona y solo desea ofrecer una lista de valores posibles en un desplegable (sin aplicar personalizaciones adicionales), puede usar SelectSimple.
SelectSimple solo es usable para parámetros nombrados.
Ejemplo:
La mayor diferencia (aparte de ser mucho más corto) con nuestro ejemplo anterior es que $ExtraWorkflowTime siempre es visible.
Modificadores
Cada parámetro puede tener uno o más de los siguientes modificadores:
"DisplayName": "texto"- Mostrar "texto" como nombre del parámetro en la IU"Hide": true / false- Ocultar este parámetro"Mandatory": true / false- Requerir que se rellene este parámetro"ReadOnly": true / false- Proteger este parámetro para que no sea cambiado desde su valor predeterminado"DefaultValue": "..."- Establecer un valor predeterminado para este parámetro. (También puede usarDefaulten su lugar.)"GraphFilter": "startswith(DisplayName, 'LIC_')"- ver Filtrado de Graph"AllowEdit": true / false- Evitar la edición manual de este parámetro. (combínelo con plantillas)
Configuración
Configuración le permite almacenar datos de configuración como nombres de cuentas de almacenamiento de Azure en un lugar central, manteniéndolos separados de sus runbooks.
Puede acceder a valores individuales desde el bloque param de un runbook usando Use-RJInterface.
Tomemos este bloque param de ejemplo de un runbook:
El portal intentará rellenar previamente cada parámetro con valores del almacén de datos central, si están presentes. Esto también funciona si el parámetro ha sido ocultado en la IU.
Un posible JSON en el almacén de datos para este runbook sería:
El elemento faltante Contenedor simplemente no se rellenará previamente en la IU.
Plantillas
Plantillas use referencias JSON para incorporar datos - por ejemplo una larga lista de ubicaciones de oficinas - cuando use una Selecciona declaración.
Esto permite mantener una personalización neutral/reutilizable/separada de los datos reales.
Tomemos el ejemplo de la incorporación de nuevos usuarios. Puede tener múltiples opciones dadas para departamentos o ubicaciones de oficina, donde asignar una ubicación de oficina también exige cierta dirección, país, estado, etc.
El siguiente ejemplo de personalización de un runbook usa la $ref dentro del Runbooks sección para referenciar/importar un subárbol desde la sección Plantillas . Busque los $id/$values palabras clave. Tenga en cuenta que $id/$values deben definirse antes de referenciarlos usando $ref. Por eso Plantillas está definido antes de Runbooks en este ejemplo.
En este ejemplo le decimos al portal que obtenga el subárbol con el $id llamado LocationOptions e incluya sus $values, reemplazando la declaración $ref Así, el portal renderizará un Selecciona como se describe en la sección Runbooks pero incluirá las opciones reales de Plantillas.
Una plantilla puede contener cualquier declaración que sea compatible en la ubicación de referencia. En este ejemplo, usamos una Personalización declaración para modificar otros parámetros como StreetAddress.
Así, podemos tener una personalización específica del runbook en Runbooks reutilizable a través de múltiples entornos, manteniendo los datos reales separados.
Esto creará la siguiente IU:
Filtros de Graph
Puede preparar Filtros ODATA de Graph para usarse en múltiples runbooks. Almacénelos en una sección llamada GraphFilters.
El siguiente ejemplo filtra por cierto prefijo en el DisplayName de un grupo, para mostrar solo los grupos relacionados con licencias en un selector de grupos.
Vea Filtrado de Graph sobre cómo usar esto desde un runbook.
Última actualización
¿Te fue útil?