Crear integraciones con Monosync
Qué ha cambiado
Cada actualización del contenido se versiona. Seleccione una versión para compararla con la anterior.
Versión 7 → 8
ActualizaciónNuevo módulo sobre trabajos de integración en detalle para que el curso cubra el examen MCIE: orígenes de plataforma, recarga de esquemas, variables en cada sintaxis, errores de mapeo y orden de filas, acciones de eliminación, vínculos, la API de objetos, exportación e importación, tiempos de espera, y cómo detener y recuperar ejecuciones. Corregido: una acción que lanza una excepción desactiva la integración. Se añadieron diagramas y listas de primera comprobación a las lecciones nuevas.
3 lecciones actualizadasduración
Actualización de contenido. Se notificó a los estudiantes inscritos.
La duración cambió de 22 a 25 minutos.
Una integración que funciona en una demo puede comportarse mal con datos reales. Las causas son casi siempre unas pocas reglas sobre orígenes, esquemas y filas de mapeo. Esta lección las recorre en el orden en que una ejecución se las encuentra.
### Leer el almacén de objetos de Monosync
Un origen de tipo `Integration Platform` lee los objetos propios de Monosync. Su ajuste `Use only updated items` es lo que hace pequeño un `Incremental Sync`: sin él, una ejecución incremental toma todos los objetos y dura tanto como una completa. No busque la respuesta en `Priority`. Ese campo se guarda, pero el código de ejecución no lo lee.
### Reload restablece sus indicadores
`Reload` sobre un esquema que ya existe sustituye cada propiedad no personalizada por la lista actual del proveedor. Las propiedades que usted creó se mantienen, pero `Key`, `Identity` y los demás indicadores de las propiedades del proveedor vuelven a los valores del proveedor. Una ejecución Link empareja por la propiedad `Key` del esquema de destino y guarda el valor `Identity`, así que tras una recarga descuidada los usuarios existentes ya no se encuentran y una acción Create tropieza con cuentas que ya existen. Revise los indicadores después de `Reload` y antes de `Save`.
### Los secretos van en variables
Un ajuste de origen con el icono de candado solo se enmascara en pantalla. Los ajustes del origen se guardan como JSON sin cifrar, y cada guardado de un origen escribe una fila de commit. El almacén cifrado real es una variable marcada como cifrada. Ponga la contraseña en una variable así y haga referencia a ella en el ajuste del origen como `{{Variables.AdPassword}}`. El valor se sustituye en tiempo de ejecución y al probar la conexión.
### Tres lugares, tres formas de escribirlo
| Dónde lo escribe | Cómo se escribe una variable | Ejemplo |
| --- | --- | --- |
| Ajustes de origen y parámetros de acción | Llaves dobles | `{{Variables.MailDomain}}` |
| Modificador `Formatted` en una fila de mapeo | Llaves simples, y `{0}` para el valor entrante | `{0}@{Variables.MailDomain}` |
| Modificador `Code` | Un nombre de C# | `Variables.MailDomain` |
Con la plantilla `Formatted` anterior, el valor `jdoe` y la variable `MailDomain` = `example.com` dan `[email protected]`. Una variable escrita en la forma equivocada no se sustituye, y la fila falla con un error de mapeo.
### Qué hace una fila que falla
Una fila de mapeo que lanza un error se registra para ese registro y el registro se omite. La ejecución continúa. Solo termina en error cuando fallan todos los registros. Una fila `Code` tiene que comprobar por sí misma los valores vacíos. Los registros fallidos están en `Mapping error(s) found!`, en la vista de acciones de la ejecución, y con `Include Action(s) failed on last run(s)` activado, que es el valor por defecto, las ejecuciones incrementales posteriores los recogen de nuevo una vez corregido el código.
### Orden entre filas
Las filas se evalúan en paralelo, con una excepción: una fila `Code` que asigna `Data.X = ...` se ejecuta en serie antes que todas las demás. Si una fila construye la dirección de correo a partir de un nombre de usuario que calcula otra fila, la primera debe asignar el valor calculado mediante `Data.X`. `One Time` no ayuda aquí. Se comporta como `One Way`.
::diagram scd-mapping-order
### Por qué una ejecución Link ve un cambio que no existe
Una ejecución Link compara los valores escalares por su forma de texto, y la comparación distingue mayúsculas de minúsculas. Un booleano producido por un mapeo se escribe como `True`, que nunca es igual a un valor de destino `true`, así que los mismos usuarios se marcan para actualización en cada ejecución. Abra la ventana `Values` de uno de esos objetos: `Before` y `Now` solo difieren en mayúsculas o en tipo. La solución es normalizar el valor en el mapeo, por ejemplo a texto en minúsculas.
### Las funciones se compilan en cada ejecución
Cada función se compila de nuevo cuando empieza una ejecución. `Remove` sobre una función solo comprueba el código de mapeo. Una función a la que todavía llama un interceptor, un filtro u otra función se puede eliminar, y a partir de entonces quienes la llaman no compilan y cada ejecución de las integraciones afectadas termina en error. Use `Show References` y busque el nombre en el código de interceptores y filtros antes de eliminar una función.
> Consejo: Cuando una ejecución le sorprenda, compruebe en este orden: las marcas `Key` e `Identity` tras un `Reload`, la forma de escribir cada variable según el lugar donde está, y `Mapping error(s) found!` en la vista de acciones de la ejecución.
Después del mapeo, los registros llegan a las acciones. Aquí es donde una integración escribe en un sistema real, así que estas son las reglas que más importan.
### Dónde filtrar
| Lugar | Qué ve | Para qué usarlo |
| --- | --- | --- |
| Generador de reglas en la pestaña `Sources` de la integración | Registros del origen | Seleccionar filas en el lado del origen |
| Interceptor `After Source Fetch` | Campos sin procesar de los orígenes elegidos | Descartar o cambiar registros con código antes del mapeo |
| Interceptor `After Mapping` | Registros mapeados | Ajustar la lista mapeada antes de las acciones |
| Filtro en una acción | Los valores mapeados, del lado del destino | Decidir qué registros recibe esa acción |
Un campo que no está mapeado en ningún sitio solo puede evaluarse en los dos primeros lugares. Una excepción en un interceptor termina la ejecución en error, así que prefiera el filtro de origen simple cuando sea suficiente.
::diagram scd-filter-places
### Eliminar requiere `None` y un filtro
Una acción recibe los registros que coinciden con su `Projection`. `Create` y `Update` siguen el vínculo del objeto. Una acción de tipo eliminación, como deshabilitar las cuentas de quienes se van, es la excepción: en las ejecuciones de sincronización la proyección `Remove` no selecciona ningún registro, y el registro de la acción dice `No need to take action. There is no data for this projection.` Configure la acción con la proyección `None` y un filtro que seleccione las bajas. Como los filtros de acción leen valores mapeados, el indicador de baja debe ser una propiedad mapeada.
### Una acción fallida y una excepción son cosas distintas
| Qué ocurre en una acción | Efecto en la ejecución |
| --- | --- |
| Algunos elementos terminan con Warning o Error | El registro de la acción lo muestra, y la acción siguiente se ejecuta igualmente |
| La acción lanza una excepción, por ejemplo por un filtro no válido o un fallo del proveedor | Las acciones posteriores no se ejecutan, la ejecución pasa a Error y la integración se desactiva |
En ambos casos, el trabajo de las acciones anteriores se mantiene. No se revierte nada. Tras una excepción, corrija la causa y active de nuevo la integración.
### Pasar datos del registro a un script
La acción `Execute Script` de PowerShell puede recibir valores del registro de dos formas. Un marcador `{{Data.displayName}}` se pega en el texto del script, de modo que un valor con una comilla o un punto y coma cambia el código que se ejecuta con los derechos de la cuenta configurada. Una entrada con nombre en `Parameters` se pasa como valor:
```
param($DisplayName, $Sam)
Set-ADUser -Identity $Sam -DisplayName $DisplayName
```
Use `Parameters` para todo lo que proceda de datos del registro.
### Los vínculos deciden entre Create y Update
Una ejecución Link empareja cada objeto con una fila del destino mediante la propiedad `Key` del esquema de destino y guarda en el vínculo el valor `Identity` de la fila. Elija una `Key` estable y única en ambos sistemas, como un número de empleado. Los nombres visibles cambian y se repiten.
Un vínculo se encuentra por objeto, origen y proveedor, no por integración. Si las integraciones A y B escriben en el mismo origen, un vínculo creado por A hace que B también trate el objeto como vinculado. Borrar los vínculos de B deja los de A en su sitio, y B sigue enviando el objeto a su acción Update.
### Escribir objetos mediante la API REST
```
PATCH /api/v1/objects/employee/1042
Api-Key: <clave>
{ "department": "Sales" }
```
| Método | Propiedades que faltan en el cuerpo |
| --- | --- |
| `POST`, `PUT` | Sus valores se eliminan |
| `PATCH` | Sus valores se conservan |
Cada escritura por API registra un cambio de objeto, incluso cuando no cambió ningún valor, de modo que el objeto entra en la siguiente ejecución incremental. Envíe solo cambios reales.
### Exportar e importar entre entornos
`Settings` exporta las integraciones, orígenes, tipos de objeto, variables y funciones elegidos a un fichero JSON y lo importa en otro lugar, elemento por elemento. Un elemento entrante se empareja por ID y después por nombre, y una coincidencia solo se sustituye con `Overwrite all objects`. Antes de importar en producción con esa opción, recuerde tres cosas: los orígenes seleccionados traen consigo sus servidores y contraseñas de prueba, así que desmárquelos; una integración importada o sobrescrita queda inactiva, así que actívela después; y los registros de objetos no forman parte de la exportación.
Una ejecución es el momento en que una integración toca de verdad un sistema de destino. La mayoría de las sorpresas en operación tienen que ver con tres preguntas: cuándo empieza una ejecución, por qué no empezó y qué queda atrás cuando se detiene a medias. Esta lección las responde en ese orden.
### Cuatro formas de iniciar una ejecución
| Inicio | Cuándo | Recuerde |
| --- | --- | --- |
| Programación | Una hora cron en la pestaña `Triggers`, evaluada en UTC | Un modo de ejecución por programación |
| Bucle sin programación | La integración está activa y no tiene ninguna programación habilitada | Se ejecuta de forma continua, una tras otra |
| `Run Once` | Solo en una integración inactiva | Escribe de verdad |
| `Calculate` | En cualquier momento, con un modo elegido | Un simulacro que nunca llama a las acciones de destino |
El bucle sin programación sorprende a quien activa una integración antes de añadir su programación. La integración no espera. Se ejecuta de inmediato y de nuevo tras cada ejecución, como Full Sync cuando en el último día no ha empezado ningún Full Sync sin programación con éxito, y si no como Incremental Sync. Añada primero la programación y después active.
### Las horas perdidas no se recuperan
La siguiente hora programada es la siguiente ocurrencia cron posterior al más tardío de dos momentos: el último inicio de trabajo de esa programación y la activación. Una integración desactivada durante un fin de semana no ejecuta las dos horas que perdió cuando la activa el lunes. Terminar el modo de mantenimiento se comporta igual. Si el trabajo perdido hace falta, inícielo de forma deliberada.
### Una ejecución por integración
Monosync nunca ejecuta dos trabajos de una misma integración a la vez. Una ejecución que se solaparía se omite con `This integration is running in another task.` Su fila en `Integration Jobs` queda inactiva y más tarde se cierra como Aborted. Varias filas Aborted con `Start / End` vacío son por tanto omisiones, no fallos. Una causa habitual es una programación que se dispara con más frecuencia de lo que dura una ejecución.
### El tiempo de espera
| Ajuste | Valor | Significado |
| --- | --- | --- |
| `Timeout (in seconds)` en la integración | Mayor que 0 | La ejecución se cancela tras ese número de segundos |
| `Timeout (in seconds)` en la integración | 0 o vacío | Se aplica el valor por defecto del servicio |
| `MONOSYNC_SERVICE_INTEGRATION_TIMEOUT_SECONDS` en los nodos de servicio | Por defecto `14400` | Cuatro horas para cada integración sin tiempo de espera propio |
Una ejecución que alcanza el límite termina como Aborted. Una sincronización completa que necesita cinco horas en una instalación por defecto se aborta siempre hasta que dé a la integración su propio valor, por ejemplo `21600` para seis horas. `Cron Buffer (in minutes)` y `Priority` se guardan pero no se leen, así que no ayudan.
### Detener una ejecución
`Integration Jobs` es de solo lectura y solo tiene el botón `Refresh`. Para detener un trabajo en curso, desactive la integración y responda a la pregunta con `Yes, stop also running tasks`.
### Después de una ejecución abortada
Las escrituras en el destino se guardan acción por acción, y un cambio de objeto solo se registra como procesado cuando su procesamiento tuvo éxito. De un aborto en mitad de las acciones se derivan dos consecuencias:
- Las escrituras ya realizadas permanecen en el destino.
- La siguiente ejecución incremental vuelve a tomar los mismos cambios de objeto.
La fecha de datos de la integración solo avanza tras un Sync correcto, así que no se pierde nada. Pero las acciones de destino deben tolerar una repetición: una actualización aplicada dos veces tiene que dar el mismo resultado que una aplicada una vez.
::diagram scd-run-after-abort
### Qué comprobar primero
- Ejecuciones una tras otra: ¿está activa la integración sin una programación habilitada?
- Filas Aborted con `Start / End` vacío: son omisiones, así que compare el intervalo de la programación con lo que dura una ejecución.
- Un Full Sync largo que siempre termina Aborted: dé a la integración su propio `Timeout (in seconds)`.