Zum Hauptinhalt springen

Datensätze sicher synchronisieren

Eine zuverlässige Synchronisierung ist ein kleiner Zustandsautomat und keine Schleife, die jeden HTTP-Aufruf wiederholt. Legen Sie die Eigentümerschaft je Wert fest, ordnen Sie stabile Identitäten zu, nutzen Sie Ersatzsemantik bewusst und kombinieren Sie signierte Webhooks mit regelmäßigem Abgleich.

Zuerst Eigentümerschaft festlegen​

Dokumentieren Sie für jeden synchronisierten Bereich genau eine Richtung:

BereichMöglicher EigentümerBedeutung
Objekt- und AttributdefinitionenTourfold-Administrator oder ProvisionierungsdienstZwei Schemaschreiber können gegenseitig deklarative Felder löschen
Skalares AttributQuellsystem, Tourfold oder ausdrücklich zusammengeführtVerhindert Aktualisierungsschleifen und Last-Writer-Überraschungen
BeziehungskanteObjekt mit dem deklarierenden BeziehungsattributVerwaltete Rückfelder sind nicht beschreibbar
AuswahlkatalogSchemaeigentümerDatensatzschreiber dürfen keine Optionen erfinden
LöschenEin verbindliches System plus AbgleichsregelEin verpasstes Löschen ist aus aktuellen Datensätzen allein nicht rekonstruierbar

Machen Sie nicht beide Systeme für dasselbe Feld verbindlich, ohne Konfliktlösung, Zeitannahmen und Schleifenunterdrückung festzulegen.

Identitätszuordnung aufbauen​

Speichern Sie für jeden Workspace:

  • Workspace-Identität;
  • Objekt-UUID und aktuellen Slug;
  • Attribut-UUIDs und aktuelle Slugs;
  • Options-/Status-UUIDs und aktuelle Werte; und
  • Tourfold-Datensatz-UUID zusammen mit der ID des Quellsystems.

Modellieren Sie die Quellsystem-ID nach Möglichkeit als eindeutiges Textattribut. Damit ist ein lesbarer Einzeltreffer möglich:

GET /api/v2/objects/equipment/records/by/source_id?attribute_value=erp-4711

Die Datensatz-UUID bleibt die primäre Tourfold-Identität. Ein fachlicher Schlüssel kann nach den Regeln des Quellsystems umbenannt oder neu vergeben werden; halten Sie beides in Ihrer Zuordnung fest.

Schema initialisieren​

  1. Vollständigen Objektkatalog lesen und Objekte zuerst über gespeicherte ID, dann über Slug finden.
  2. Fehlende Objekte anlegen und jede vom Server vergebene Kind-ID speichern.
  3. Bei deklarativem PUT alle eigenen Attribute des Objekts samt bestehender IDs senden.
  4. Verwaltete Rückbeziehungen im Ersatzdokument des Zielobjekts auslassen.
  5. lock_version mitsenden; bei Konflikt neu lesen und zusammenführen, statt veralteten Zustand zu wiederholen.

Dürfen Administratoren dasselbe Objekt erweitern, muss ein Provisionierungsdienst diese Felder erhalten oder ein klar getrenntes Objekt besitzen. Deklarative Ersetzung ist absichtlich kein Patch.

Neue Datensätze atomar importieren​

Legen Sie unabhängige Datensätze einzeln an und speichern Sie die zurückgegebene UUID sofort. Für neue verbundene Datensätze verwenden Sie POST /api/v2/records/batch: Der Endpoint akzeptiert 1–100 Datensätze über mehrere Objekte in einer Transaktion.

{
"items": [
{
"object": "equipment",
"key": "equipment:erp-4711",
"data": {
"source_id": "erp-4711",
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17"
}
},
{
"object": "maintenance_request",
"key": "request:erp-9902",
"data": {
"source_id": "erp-9902",
"title": "Temperature too high on third floor",
"equipment": [{"ref": "equipment:erp-4711"}]
}
}
]
}

Request-lokale key-Werte gelten nur innerhalb des Batches. Ein ref verknüpft ein anderes Element. Ist ein Element, eine Einschränkung oder Beziehung ungültig, wird der gesamte Batch zurückgerollt; kein zurückgegebenes Element darf als angelegt gespeichert werden.

Batch-Erstellung ist atomar, aber kein Upsert und macht ein wiederholtes POST nicht idempotent. Geht eine Antwort verloren, gleichen Sie über den eindeutigen Quellschlüssel ab, bevor Sie erneut anlegen.

Änderungen mit Merge-Semantik anwenden​

Datensatz-PATCH folgt JSON Merge Patch:

Zustand im PayloadBedeutung
Attribut in data ausgelassenUnverändert lassen
Attribut enthält einen WertAktuellen Wert ersetzen
Optionales Attribut ist nullLöschen
Beschreibbares Array ist []Durch leere Menge ersetzen

Senden Sie nur Felder, die diese Synchronisierung besitzt. So überschreiben Sie weder von Tourfold noch von einem anderen System verwaltete Werte.

{
"lock_version": 12,
"data": {
"name": "Rooftop HVAC Unit RTU-17A",
"certifications": ["tuv", "iso_9001"]
}
}

Ein Array ist immer der vollständig gewünschte Wert und niemals eine Append-Operation. Bei geteilter Eigentümerschaft erst lesen, zusammenführen und schreiben; schützen Sie diese Folge mit lock_version. Eine veraltete Version liefert 409. Lesen Sie den aktuellen Zustand, wenden Sie Ihre Eigentumsregeln erneut an und senden Sie den neu konstruierten Patch.

Beziehungsarrays folgen derselben Ersatzregel nur am deklarierenden Eigentümerattribut. Eine verwaltete Rückbeziehung ist eine schreibgeschützte Projektion. Möchte ein Ablauf von der Zielseite eine Kante hinzufügen oder entfernen, muss er den entsprechenden Eigentümerdatensatz ändern.

Bestehende Datensätze abgleichen​

Nutzen Sie POST /objects/{object_ref}/records/query für einen flachen paginierten Scan. Die Seitengröße beträgt höchstens 100. Sortieren Sie ausdrücklich stabil und behalten Sie Quellschlüssel und Tourfold-ID im verarbeiteten Ergebnis.

{
"filter": {
"updated_at": {"gte": "2026-08-27T00:00:00Z"}
},
"sort": ["updated_at:asc", "id:asc"],
"page": 0,
"size": 100
}

Dies ist eine Abfrage des aktuellen Zustands und kein snapshot-isolierter Änderungsstrom. Datensätze können während des Scans zwischen Seiten wechseln; gelöschte Datensätze fehlen. Verwenden Sie überlappende Zeitfenster und entdoppeln Sie über die Datensatz-ID, wenn updated_at als High-Water-Hinweis dient. Ein regelmäßiger vollständiger Inventarabgleich macht verpasste Löschungen und langfristige Abweichungen sichtbar.

GraphQL ist nützlich, wenn ein Abgleich verknüpften Kontext benötigt. Tiefen- und Zeilenkostenlimits machen es aber zum falschen Standard für Massenexport. Verwenden Sie REST-Paginierung für große Datenbewegungen und GraphQL für gezielte Graphabfragen.

Webhooks als schnellen Pfad verwenden​

Abonnieren Sie konkrete Datensatzereignisse oder ein Objektmuster wie object.equipment.*. Ein Webhook meldet eine Änderung schnell; REST liefert den aktuellen verbindlichen Zustand.

Ihr Empfänger sollte:

  1. die Signatur über die exakten Request-Bytes prüfen;
  2. ein Zeitstempel-Toleranzfenster erzwingen;
  3. webhook-id in eine Tabelle mit Unique Constraint einfügen;
  4. das Ereignis in derselben lokalen Transaktion dauerhaft einreihen;
  5. innerhalb von fünf Sekunden mit 2xx antworten; und
  6. asynchron verarbeiten sowie unbekannte Payload-Felder tolerieren.

Die Zustellung erfolgt At-least-once und ohne Reihenfolgegarantie. Dieselbe webhook-id bleibt über Wiederholungen stabil; entdoppeln Sie darüber. Ist Reihenfolge wichtig, vergleichen Sie timestamp und lesen Sie abschließend den aktuellen REST-Zustand, statt der Eingangsreihenfolge zu vertrauen.

Zustellfehler sind kein vollständiges Zustellungsprotokoll: Sie erfassen Nachrichten, die mindestens einmal fehlgeschlagen sind, nicht jeden erfolgreichen Versuch. Überwachen Sie ausgeschöpfte Fehler, aber führen Sie ein eigenes Verarbeitungsjournal und einen Abgleichsjob.

Wiederholung je Operation​

OperationSichere Strategie
GET / QueryVorübergehende Transport-/Serverfehler mit begrenztem exponentiellem Backoff wiederholen
PATCH mit lock_versionNach verlorener Antwort aktuellen Zustand lesen; bei 409 zusammenführen und neu konstruierten Patch senden
Deklaratives Schema-PUTAktuelle Definition/Version lesen und vollständiges Solldokument neu erzeugen
Datensatz- oder Batch-POSTNach mehrdeutiger Antwort nicht blind wiederholen; zuerst eindeutige Quellschlüssel nachschlagen
Webhook-VerarbeitungÜber webhook-id entdoppeln; Duplikat bestätigen, ohne es erneut anzuwenden

Validierungs-, Authentifizierungs-, Berechtigungs- und Schemafehler sind nicht vorübergehend. Verzweigen Sie auf RFC-9457-Problem-type und Status. Nur bei 401 wegen abgelaufenem Token einmal aktualisieren und wiederholen; andere Berechtigungsfehler benötigen andere Zugangsdaten oder Grants.

Synchronisierungsschleifen verhindern​

Wenn Tourfold und Quelle beide Änderungen aussenden:

  • zuletzt angewendete Quellversion oder Inhalts-Hash speichern;
  • eigene Felder vor dem Schreiben vergleichen und No-op-Patches auslassen;
  • Korrelationsinformationen im Verarbeitungsjournal behalten;
  • nie nur über einen veränderlichen Slug routen; und
  • Webhook-Verarbeitung unabhängig von API-Request-Idempotenz idempotent machen.

Ein durch Ihren eigenen Schreibzugriff ausgelöster Webhook ist normal. Der Empfänger sollte erkennen, dass der gewünschte Zustand bereits vorliegt, und ohne weiteren Schreibzugriff abschließen.

Prüfliste für den Produktivbetrieb​

  • Jedes synchronisierte Feld und jede Beziehung hat einen dokumentierten Eigentümer.
  • Zuordnungsschlüssel enthalten Workspace-, Objekt- und Datensatzidentität.
  • Quell-IDs sind eindeutig, wenn ein Einzeltreffer erforderlich ist.
  • Mehrdeutige POST-Ergebnisse werden vor einer Wiederholung abgeglichen.
  • Arrays und Beziehungen auf der Eigentümerseite gelten als Ersatzmengen.
  • Gleichzeitige Änderungen verwenden lock_version und eine Merge-Regel.
  • Webhooks werden signaturgeprüft, dauerhaft eingereiht, entdoppelt und ungeordnet verarbeitet.
  • Vollständiger Abgleich deckt verpasste Ereignisse und Löschungen ab.
  • Logs enthalten Request-/Korrelations-IDs, aber keine Bearer-Token oder Webhook-Secrets.

Für Schemaänderungen an der Zuordnung siehe Ein produktives Objektschema weiterentwickeln.