Detectar y desduplicar registros usando funciones hash en Jitterbit Studio

Introducción

Las funciones hash proporcionan a cada registro una huella digital corta y de longitud fija derivada de sus valores de campo. Dos registros con valores de campo idénticos producen huellas digitales idénticas; un registro cuyos valores han cambiado produce una huella digital diferente a la calculada en la ejecución anterior. Studio proporciona dos funciones hash criptográficas para este fin: SHA256, que devuelve una cadena hexadecimal de 64 caracteres, y MD5, que devuelve una cadena hexadecimal de 32 caracteres.

Esta guía cubre dos patrones basados en estas funciones:

• Parte 1: Detección de cambios entre ejecuciones: Calcular un hash de cada registro de origen durante una ejecución de sincronización, compararlo con el hash almacenado en caché de la ejecución anterior y omitir registros cuyo hash no ha cambiado.
• Parte 2: Deduplicación dentro de la ejecución: Rastrear qué registros ya se han procesado durante una única ejecución usando caché y omitir registros duplicados encontrados posteriormente en el mismo conjunto de datos.

Ambos patrones utilizan las funciones de caché en la nube de Harmony ReadCache y WriteCache para almacenar estado. Las llamadas de caché están sujetas a un límite combinado de 100 llamadas por minuto por organización; para necesidades de almacenamiento de alto volumen o larga duración, Cloud Datastore es la alternativa recomendada.

Esta guía asume familiaridad con las condiciones de transformación. Para obtener más información, consulta Filtrar registros usando condiciones.

Patrón de diseño

Ambos patrones utilizan una única operación:

El nodo de condición de transformación se ejecuta una vez por cada registro de origen. El script de condición lee del caché, evalúa si procesar el registro y devuelve true (procesar) o false (omitir). Cuando se procesa un registro, el script también escribe estado actualizado en caché para usarlo en la siguiente evaluación.

La lógica de caché reside en la condición de transformación en lugar de en un paso de script separado. Esto mantiene la administración del estado cerca de los datos y evita la complejidad de coordinar qué registros se procesaron a través de un límite de paso.

Parte 1: Detección de cambios basada en hash entre ejecuciones

Este patrón detecta si un registro de origen ha cambiado desde la última ejecución de integración. Un hash de los campos de cada registro se almacena en caché con una expiración de 30 días para que persista entre ejecuciones.

Paso 1: Elegir una función hash

Utiliza SHA256 a menos que la velocidad de procesamiento sea la preocupación principal. SHA256 devuelve una cadena hexadecimal de 64 caracteres y no tiene vulnerabilidades de colisión prácticas conocidas para este caso de uso. MD5 devuelve una cadena hexadecimal de 32 caracteres y es ligeramente más rápido, pero produce una huella digital más débil.

Para la mayoría de volúmenes de integración, la diferencia de rendimiento es insignificante. Utiliza SHA256 por defecto.

Paso 2: Construir la entrada hash

Concatena los campos que deben activar el procesamiento cuando cambien. Utiliza | como separador entre valores de campo para evitar que valores adyacentes produzcan la misma cadena concatenada accidentalmente.

Por ejemplo, si un registro de contacto debe procesarse cuando email, first_name o last_name cambien:

Source.id + "|" + Source.email + "|" + Source.first_name + "|" + Source.last_name

Paso 3: Escribe el script de condición

Abre la transformación y agrega un script de condición al nodo raíz. El script lee el hash almacenado, calcula el hash actual y devuelve true o false.

Reemplaza Source.id, Source.email, Source.first_name y Source.last_name con los nombres de campo reales de tu esquema de origen. Reemplaza "my_project" con un prefijo estable que identifique la integración: esto evita colisiones de claves de caché con otras operaciones en el mismo entorno.

// Build the cache key using a stable prefix and the record's unique ID
cacheKey = "my_project_contact_hash_" + Source.id;

// Read the hash stored from the previous run (env scope, 30-day expiration)
storedHash = ReadCache(cacheKey, 2592000, "env");

// Compute the hash of the fields that matter for this record
currentHash = SHA256(Source.id + "|" + Source.email + "|" + Source.first_name + "|" + Source.last_name);

// Write the current hash back to cache.
// If the record is unchanged, this renews the cache expiration timer.
// If the record changed, this updates the stored hash for the next run.
WriteCache(cacheKey, currentHash, 2592000, "env");

// Return true to process the record, false to skip it
If(storedHash == currentHash, false, true);

Puntos clave sobre este script:

• ReadCache devuelve null cuando no hay valor almacenado para la clave (por ejemplo, en la primera ejecución o después de una expiración de caché). Un hash almacenado null nunca es igual al hash calculado, por lo que todos los registros se procesan en la primera ejecución.
• Se llama a WriteCache para cada registro, incluidos los que no han cambiado. Para registros sin cambios, esto renueva la expiración de 30 días sin modificar el valor almacenado.
• 2592000 es la expiración máxima de caché en segundos (30 días). Ajusta este valor si tu sincronización se ejecuta con menos frecuencia y los registros podrían no aparecer en ejecuciones consecutivas.
• El alcance "env" hace que la entrada de caché sea visible para todas las operaciones en el mismo entorno y hace que persista entre ejecuciones separadas. El alcance "project" predeterminado no persiste entre ejecuciones.

Paso 4: Asigna campos de origen al destino

Con la condición en su lugar, asigna campos de la actividad de origen a la actividad de destino en la transformación como de costumbre. Los registros para los que la condición devuelve false se omiten: no se ejecuta ninguna asignación de destino para esos registros.

Parte 2: Deduplicación dentro de la ejecución mediante caché

Este patrón detecta registros duplicados dentro de una única ejecución de operación. Es apropiado cuando un conjunto de datos de origen puede contener el mismo registro más de una vez (por ejemplo, un informe que devuelve una fila por línea de transacción, lo que puede resultar en que la misma ID de cliente aparezca varias veces).

Las entradas de caché escritas en este patrón utilizan la expiración predeterminada de 30 minutos y el alcance "project" (ambos predeterminados). La ventana de 30 minutos es lo suficientemente larga para abarcar una única ejecución, y el alcance de proyecto es apropiado porque el estado de dedup no necesita sobrevivir más allá de la ejecución actual.

Paso 1: Elige una clave de dedup

Identifica el campo o la combinación de campos que hacen que un registro sea único. Si el registro de origen tiene un campo de clave principal como id u order_id, úsalo directamente. Si la unicidad depende de una combinación de campos, concatenalos con separadores |.

• Opción A: Campo de ID único

  Source.customer_id
  

• Opción B: Clave compuesta

  Source.order_id + "|" + Source.line_number
  

Paso 2: Escribe el script de condición

Abre la transformación y agrega un script de condición al nodo raíz.

Reemplaza "my_project_dedup_" con un prefijo estable y reemplaza Source.customer_id con la clave de dedup del Paso 1.

// Build the dedup cache key
dedupeKey = "my_project_dedup_" + Source.customer_id;

// Check whether this key has been seen already in this run
existing = ReadCache(dedupeKey);

If(existing == null,
    // First occurrence: mark this key as seen and process the record
    WriteCache(dedupeKey, "1");
    true;
,
    // Duplicate: skip the record
    false;
);

Puntos clave sobre este script:

• ReadCache sin argumentos de expiración o alcance utiliza la expiración predeterminada de 30 minutos y el alcance "project", que es apropiado para el estado dentro de la ejecución.
• WriteCache(dedupeKey, "1") almacena un valor de marcador de posición. El valor en sí no importa: la presencia de la clave en caché es la señal.
• La primera vez que se encuentra una clave, la condición devuelve true y se procesa el registro. Cada aparición posterior de la misma clave devuelve false y se omite.

Paso 3: Asignar campos de origen al destino

Asigna campos de la actividad de origen a la actividad de destino como de costumbre. Se omiten los registros para los cuales la condición devuelve false.

Verificar la integración

Verificar la Parte 1 (detección de cambios entre ejecuciones)

1. Implementa y ejecuta la operación por primera vez contra tus datos de origen.

2. En los registros de operación, confirma que se procesaron todos los registros. En la primera ejecución, ReadCache devuelve null para cada registro (aún no existe hash almacenado), por lo que la condición de cada registro devuelve true.

3. Ejecuta la operación una segunda vez sin modificar ningún registro de origen.

4. En los registros de operación, confirma que no se procesó ningún registro. Todos los hashes almacenados ahora coinciden con los hashes calculados, por lo que cada condición devuelve false.

5. Modifica un registro de origen y ejecuta la operación una tercera vez.

6. En los registros de operación, confirma que se procesó exactamente el registro modificado y se omitieron todos los demás.

7. Si los registros se omiten de manera inesperada en la primera ejecución, confirma que el alcance del caché en ReadCache y WriteCache sea "env" y que la expresión de clave de caché sea idéntica en ambas llamadas. Una discrepancia en el alcance o nombre de clave causa que ReadCache siempre devuelva null, lo que significa que los cambios siempre se detectan pero los hashes se escriben en una clave inaccesible.

Verificar la Parte 2 (deduplicación dentro de la ejecución)

1. Prepara un conjunto de datos de origen que contenga al menos dos registros con el mismo valor de clave de deduplicación.

2. Implementa y ejecuta la operación.

3. En los registros de operación, confirma que solo se escribió un registro en el destino para cada clave de deduplicación única y que se omitieron los registros duplicados.

4. Ejecuta la operación una segunda vez usando los mismos datos de origen.

5. Confirma que la primera aparición de cada clave de deduplicación se procesa de nuevo. La expiración de caché predeterminada de 30 minutos significa que el estado de deduplicación no se mantiene entre ejecuciones: cada ejecución comienza de nuevo.

   Nota

   Si ejecutas la operación dos veces en 30 minutos, las entradas de caché de la primera ejecución siguen activas. En ese caso, la segunda ejecución omite todos los registros como duplicados, que es el comportamiento esperado. Espera a que expire el caché antes de volver a ejecutar, o usa un prefijo de clave de deduplicación diferente para aislar las ejecuciones de prueba.

6. Si los duplicados no se están omitiendo, verifica que la expresión de clave de deduplicación produzca un valor estable y no vacío para cada registro. Una clave que se evalúa como null o una cadena vacía causa que cada registro parezca único.