Erkennung und Deduplizierung von Datensätzen mit Hash-Funktionen in Jitterbit Studio

Einführung

Hash-Funktionen erzeugen für jeden Datensatz einen kurzen, festen Fingerabdruck basierend auf seinen Feldwerten. Zwei Datensätze mit identischen Feldwerten erzeugen identische Fingerabdrücke; ein Datensatz, dessen Werte sich geändert haben, erzeugt einen anderen Fingerabdruck als beim vorherigen Durchlauf berechnet. Studio stellt zwei kryptografische Hash-Funktionen für diesen Zweck bereit: SHA256, die eine 64-stellige Hex-Zeichenkette zurückgibt, und MD5, die eine 32-stellige Hex-Zeichenkette zurückgibt.

Diese Anleitung behandelt zwei Muster, die auf diesen Funktionen aufbauen:

• Teil 1: Änderungserkennung über mehrere Durchläufe: Berechne einen Hash jedes Quelldatensatzes während einer Synchronisierung, vergleiche ihn mit dem Hash, der im Cache aus dem vorherigen Durchlauf gespeichert ist, und überspringe Datensätze, deren Hash sich nicht geändert hat.
• Teil 2: Deduplizierung innerhalb eines Durchlaufs: Verfolge mit Hilfe des Caches, welche Datensätze bereits während eines einzelnen Durchlaufs verarbeitet wurden, und überspringe doppelte Datensätze, die später im selben Datensatz auftauchen.

Beide Muster verwenden die Harmony-Cloud-Cache-Funktionen ReadCache und WriteCache, um Zustand zu speichern. Cache-Aufrufe unterliegen einer kombinierten Grenze von 100 Aufrufen pro Minute pro Organisation; für Hochlast- oder Langzeitspeicheranforderungen ist Cloud Datastore die empfohlene Alternative.

Diese Anleitung setzt Vertrautheit mit Transformationsbedingungen voraus. Weitere Informationen finden Sie unter Datensätze mit Bedingungen filtern.

Entwurfsmuster

Beide Muster verwenden einen einzelnen Vorgang:

Der Knoten der Transformationsbedingung wird einmal pro Quelldatensatz ausgeführt. Das Bedingungsskript liest aus dem Cache, bewertet, ob der Datensatz verarbeitet werden soll, und gibt true (verarbeiten) oder false (überspringen) zurück. Wenn ein Datensatz verarbeitet wird, schreibt das Skript auch den aktualisierten Zustand in den Cache zur Verwendung bei der nächsten Bewertung.

Die Cache-Logik befindet sich in der Transformationsbedingung und nicht in einem separaten Skriptschritt. Dies hält die Zustandsverwaltung nah bei den Daten und vermeidet die Komplexität der Koordination, welche Datensätze über eine Schrittgrenze hinweg verarbeitet wurden.

Teil 1: Änderungserkennung mit Hash-Funktion über mehrere Durchläufe

Dieses Muster erkennt, ob sich ein Quelldatensatz seit dem letzten Integrationsdurchlauf geändert hat. Ein Hash der Felder jedes Datensatzes wird im Cache mit einer 30-Tage-Ablaufzeit gespeichert, damit er zwischen den Durchläufen erhalten bleibt.

Schritt 1: Wähle eine Hash-Funktion

Verwende SHA256, es sei denn, Verarbeitungsgeschwindigkeit hat oberste Priorität. SHA256 gibt eine 64-stellige Hex-Zeichenkette zurück und weist für diesen Anwendungsfall keine bekannten praktischen Kollisionsschwachstellen auf. MD5 gibt eine 32-stellige Hex-Zeichenkette zurück und ist etwas schneller, erzeugt aber einen schwächeren Fingerabdruck.

Bei den meisten Integrationsmengen ist der Leistungsunterschied vernachlässigbar. Verwende standardmäßig SHA256.

Schritt 2: Konstruiere die Hash-Eingabe

Verkette die Felder, deren Änderung eine Verarbeitung auslösen soll. Verwende | als Trennzeichen zwischen Feldwerten, um zu verhindern, dass benachbarte Werte zufällig die gleiche verkettete Zeichenkette erzeugen.

Wenn beispielsweise ein Kontaktdatensatz verarbeitet werden soll, wenn sich email, first_name oder last_name ändern:

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

Schritt 3: Bedingungsskript schreiben

Öffnen Sie die Transformation und fügen Sie dem Stammknoten ein Bedingungsskript hinzu. Das Skript liest den gespeicherten Hash, berechnet den aktuellen Hash und gibt true oder false zurück.

Ersetzen Sie Source.id, Source.email, Source.first_name und Source.last_name durch die tatsächlichen Feldnamen aus Ihrem Quellschema. Ersetzen Sie "my_project" durch ein stabiles Präfix, das die Integration identifiziert: Dies verhindert Cache-Schlüsselkollisionen mit anderen Operationen in derselben Umgebung.

// 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);

Wichtige Punkte zu diesem Skript:

• ReadCache gibt null zurück, wenn für den Schlüssel kein Wert gespeichert ist (z. B. bei der ersten Ausführung oder nach Ablauf des Cache). Ein null gespeicherter Hash ist niemals gleich dem berechneten Hash, daher werden alle Datensätze bei der ersten Ausführung verarbeitet.
• WriteCache wird für jeden Datensatz aufgerufen, auch für unveränderte. Bei unveränderten Datensätzen wird die 30-tägige Ablaufzeit verlängert, ohne den gespeicherten Wert zu ändern.
• 2592000 ist die maximale Cache-Ablaufzeit in Sekunden (30 Tage). Passen Sie diesen Wert an, wenn Ihre Synchronisierung weniger häufig ausgeführt wird und Datensätze möglicherweise nicht in aufeinanderfolgenden Ausführungen angezeigt werden.
• Der Bereich "env" macht den Cache-Eintrag für alle Operationen in derselben Umgebung sichtbar und bewirkt, dass er zwischen separaten Ausführungen bestehen bleibt. Der standardmäßige Bereich "project" bleibt nicht zwischen Ausführungen bestehen.

Schritt 4: Quellfelder dem Ziel zuordnen

Wenn die Bedingung vorhanden ist, ordnen Sie Felder der Quellaktivität der Zielaktivität in der Transformation wie gewohnt zu. Datensätze, für die die Bedingung false zurückgibt, werden übersprungen: Für diese Datensätze wird keine Zielzuordnung ausgeführt.

Teil 2: Deduplizierung innerhalb einer Ausführung mit Cache

Dieses Muster erkennt doppelte Datensätze innerhalb einer einzelnen Operationsausführung. Es ist geeignet, wenn ein Quelldataset denselben Datensatz mehr als einmal enthalten kann (z. B. ein Bericht, der eine Zeile pro Transaktionszeilenelement zurückgibt, was dazu führen kann, dass dieselbe Kundennummer mehrmals angezeigt wird).

Cache-Einträge, die in diesem Muster geschrieben werden, verwenden die standardmäßige 30-Minuten-Ablaufzeit und den Bereich "project" (beide Standard). Das 30-Minuten-Fenster ist lang genug, um eine einzelne Ausführung zu umfassen, und der Projektbereich ist geeignet, da der Deduplizierungsstatus nicht über die aktuelle Ausführung hinaus bestehen bleiben muss.

Schritt 1: Deduplizierungsschlüssel wählen

Identifizieren Sie das Feld oder die Kombination von Feldern, die einen Datensatz eindeutig machen. Wenn der Quelldatensatz ein Primärschlüsselfeld wie id oder order_id hat, verwenden Sie dieses direkt. Wenn Eindeutigkeit von einer Kombination von Feldern abhängt, verketten Sie sie mit | Trennzeichen.

• Option A: Einzelnes eindeutiges ID-Feld

  Source.customer_id
  

• Option B: Zusammengesetzter Schlüssel

  Source.order_id + "|" + Source.line_number
  

Schritt 2: Bedingungsskript schreiben

Öffnen Sie die Transformation und fügen Sie dem Stammknoten ein Bedingungsskript hinzu.

Ersetzen Sie "my_project_dedup_" durch ein stabiles Präfix und ersetzen Sie Source.customer_id durch den Deduplizierungsschlüssel aus Schritt 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;
);

Wichtige Punkte zu diesem Skript:

• ReadCache ohne Ablauf- oder Bereichsargumente verwendet die standardmäßige 30-Minuten-Ablaufzeit und den Bereich "project", was für den Zustand innerhalb einer Ausführung geeignet ist.
• WriteCache(dedupeKey, "1") speichert einen Platzhalterwert. Der Wert selbst spielt keine Rolle: Das Vorhandensein des Schlüssels im Cache ist das Signal.
• Beim ersten Mal, wenn ein Schlüssel angetroffen wird, gibt die Bedingung true zurück und der Datensatz wird verarbeitet. Jedes nachfolgende Vorkommen desselben Schlüssels gibt false zurück und wird übersprungen.

Schritt 3: Quellfelder auf das Ziel abbilden

Bilden Sie Felder aus der Quellaktivität wie gewohnt auf die Zielaktivität ab. Datensätze, für die die Bedingung false ergibt, werden übersprungen.

Integration überprüfen

Teil 1 überprüfen (operationsübergreifende Änderungserkennung)

1. Stellen Sie die Operation bereit und führen Sie sie aus zum ersten Mal gegen Ihre Quelldaten.

2. Bestätigen Sie in den Operationsprotokollen, dass alle Datensätze verarbeitet wurden. Bei der ersten Ausführung gibt ReadCache für jeden Datensatz null zurück (noch kein gespeicherter Hash vorhanden), daher ergibt die Bedingung für jeden Datensatz true.

3. Führen Sie die Operation ein zweites Mal aus, ohne Quelldatensätze zu ändern.

4. Bestätigen Sie in den Operationsprotokollen, dass keine Datensätze verarbeitet wurden. Alle gespeicherten Hashes stimmen nun mit den berechneten Hashes überein, daher ergibt jede Bedingung false.

5. Ändern Sie einen Quelldatensatz und führen Sie die Operation ein drittes Mal aus.

6. Bestätigen Sie in den Operationsprotokollen, dass genau der geänderte Datensatz verarbeitet wurde und alle anderen übersprungen wurden.

7. Falls Datensätze bei der ersten Ausführung unerwartet übersprungen werden, bestätigen Sie, dass der Cache-Bereich in sowohl ReadCache als auch WriteCache "env" ist und dass der Cache-Schlüsselausdruck in beiden Aufrufen identisch ist. Ein Unterschied im Bereich oder Schlüsselnamen führt dazu, dass ReadCache immer null zurückgibt, was bedeutet, dass Änderungen immer erkannt werden, aber Hashes in einen unerreichbaren Schlüssel geschrieben werden.

Teil 2 überprüfen (operationsinterne Deduplizierung)

1. Bereiten Sie einen Quelldatensatz vor, der mindestens zwei Datensätze mit demselben Deduplizierungsschlüsselwert enthält.

2. Stellen Sie die Operation bereit und führen Sie sie aus.

3. Bestätigen Sie in den Operationsprotokollen, dass nur ein Datensatz pro eindeutigem Deduplizierungsschlüssel ins Ziel geschrieben wurde und doppelte Datensätze übersprungen wurden.

4. Führen Sie die Operation ein zweites Mal mit denselben Quelldaten aus.

5. Bestätigen Sie, dass das erste Auftreten jedes Deduplizierungsschlüssels erneut verarbeitet wird. Das standardmäßige Cache-Ablaufdatum von 30 Minuten bedeutet, dass der Deduplizierungsstatus nicht zwischen Ausführungen übertragen wird: jede Ausführung beginnt neu.

   Hinweis

   Falls Sie die Operation zweimal innerhalb von 30 Minuten ausführen, sind Cache-Einträge aus der ersten Ausführung noch aktiv. In diesem Fall überspringt die zweite Ausführung alle Datensätze als Duplikate, was das erwartete Verhalten ist. Warten Sie, bis der Cache abläuft, bevor Sie erneut ausführen, oder verwenden Sie ein anderes Deduplizierungsschlüssel-Präfix, um Test-Ausführungen zu trennen.

6. Falls Duplikate nicht übersprungen werden, überprüfen Sie, dass der Deduplizierungsschlüsselausdruck für jeden Datensatz einen stabilen, nicht leeren Wert ergibt. Ein Schlüssel, der zu null oder einer leeren Zeichenkette wertet, führt dazu, dass jeder Datensatz als eindeutig erscheint.