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:
| Bereich | Möglicher Eigentümer | Bedeutung |
|---|---|---|
| Objekt- und Attributdefinitionen | Tourfold-Administrator oder Provisionierungsdienst | Zwei Schemaschreiber können gegenseitig deklarative Felder löschen |
| Skalares Attribut | Quellsystem, Tourfold oder ausdrücklich zusammengeführt | Verhindert Aktualisierungsschleifen und Last-Writer-Überraschungen |
| Beziehungskante | Objekt mit dem deklarierenden Beziehungsattribut | Verwaltete Rückfelder sind nicht beschreibbar |
| Auswahlkatalog | Schemaeigentümer | Datensatzschreiber dürfen keine Optionen erfinden |
| Löschen | Ein verbindliches System plus Abgleichsregel | Ein 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
- Vollständigen Objektkatalog lesen und Objekte zuerst über gespeicherte ID, dann über Slug finden.
- Fehlende Objekte anlegen und jede vom Server vergebene Kind-ID speichern.
- Bei deklarativem
PUTalle eigenen Attribute des Objekts samt bestehender IDs senden. - Verwaltete Rückbeziehungen im Ersatzdokument des Zielobjekts auslassen.
lock_versionmitsenden; 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 Payload | Bedeutung |
|---|---|
Attribut in data ausgelassen | Unverändert lassen |
| Attribut enthält einen Wert | Aktuellen Wert ersetzen |
Optionales Attribut ist null | Lö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:
- die Signatur über die exakten Request-Bytes prüfen;
- ein Zeitstempel-Toleranzfenster erzwingen;
webhook-idin eine Tabelle mit Unique Constraint einfügen;- das Ereignis in derselben lokalen Transaktion dauerhaft einreihen;
- innerhalb von fünf Sekunden mit
2xxantworten; und - 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
| Operation | Sichere Strategie |
|---|---|
GET / Query | Vorübergehende Transport-/Serverfehler mit begrenztem exponentiellem Backoff wiederholen |
PATCH mit lock_version | Nach verlorener Antwort aktuellen Zustand lesen; bei 409 zusammenführen und neu konstruierten Patch senden |
Deklaratives Schema-PUT | Aktuelle Definition/Version lesen und vollständiges Solldokument neu erzeugen |
Datensatz- oder Batch-POST | Nach 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_versionund 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.