Sync-API oder Einzelrequests
Ein fehlerhafter Datensatz in einem Stapel von zweien — und beide werden verworfen. Das ist keine Schwäche der Sync-API, sondern ihr Zweck. Nur passt er nicht zu jedem Import.
Wer Daten nach Shopware schreibt, hat zwei Wege: viele kleine Aufrufe oder einen großen. Die übliche Begründung für den großen lautet „schneller". Sie stimmt und ist der unwichtigste Teil der Entscheidung.
Was wir gemessen haben
Drei Aufrufe gegen eine laufende Installation, nach jedem die Zeilenzahl der Zieltabelle gezählt. Ausgangswert: 3 Steuersätze.
Ein gültiger und ein unvollständiger Datensatz
Zwei Datensätze im selben Stapel, beim zweiten fehlt ein Pflichtfeld.
HTTP 400
"detail": "This value should not be blank."
"source": { "pointer": "/schreibe-steuern/1/taxRate" }
Zeilenzahl danach: 3. Unverändert.
Der gültige erste Datensatz wurde ebenfalls verworfen. Das ist der entscheidende Satz dieses Artikels. Die Sync-API schreibt nicht, was geht — sie schreibt alles oder nichts.
Der Fehlerzeiger ist dabei ungewöhnlich hilfreich: /schreibe-steuern/1/taxRate
nennt den selbst vergebenen Schlüssel der Operation, den Index im Stapel und
das Feld. Wer seine Stapel durchnummeriert, findet den Übeltäter ohne Suche.
Beide Datensätze gültig
HTTP 200
{"data":{"tax":["aaaa…aa1","aaaa…aa2"]},"notFound":[],"deleted":[]}
Zeilenzahl: 5. Die Antwort nennt die geschriebenen IDs.
Derselbe Aufruf ein zweites Mal
HTTP 200
Zeilenzahl: 5. Unverändert. upsert ist idempotent — wer eine ID
mitgibt, kann denselben Stapel gefahrlos wiederholen. Für einen Import, der nach
einem Netzwerkabbruch von vorn beginnt, ist das die wichtigste Eigenschaft
überhaupt.
Die Entscheidung ist keine Mengenfrage
| Frage | Antwort ja | Antwort nein |
|---|---|---|
| Darf die Hälfte ankommen? | Einzelrequests oder kleine Stapel | Sync |
| Gehören die Datensätze fachlich zusammen? | Sync | Einzelrequests |
| Soll ein einzelner Fehler den Lauf stoppen? | Sync | Einzelrequests |
| Wird der Lauf nach Abbruch wiederholt? | Sync mit IDs — idempotent | Einzelrequests brauchen eigene Logik |
Der nächtliche Bestandsabgleich. Fünftausend Produkte, bei einem stimmt die Einheit nicht. Mit einem einzigen Sync-Aufruf sind alle fünftausend nicht geschrieben. Mit Stapeln zu hundert sind es neunundvierzig Stapel, die durchgehen, und einer, der nicht. Hier ist Teilerfolg erwünscht.
Die Bestellung mit ihren Positionen. Kopf, Positionen, Lieferung, Transaktion — halb geschrieben ist schlimmer als gar nicht geschrieben. Hier ist Alles-oder-nichts der ganze Punkt.
Der Preisimport aus dem ERP. Kommt darauf an, ob ein Preis ohne seine Staffel sinnvoll ist. Meistens nicht.
Die Stapelgröße misst man, statt sie zu schätzen
Der Kern gibt keine feste Obergrenze vor. Was begrenzt, sind PHP-Speicher, Laufzeitgrenze und die Größe der einzelnen Datensätze. Ein Produkt mit Übersetzungen, Preisen und Medienzuordnungen wiegt ein Vielfaches eines Steuersatzes.
Praktisches Vorgehen: mit hundert anfangen, Laufzeit und Speicher messen, verdoppeln, bis es kippt, dann die Hälfte des letzten funktionierenden Werts nehmen. Und im Hinterkopf behalten, dass ein größerer Stapel bei einem Fehler auch mehr verwirft.
Was wir nicht gemessen haben
Wir haben Steuersätze geschrieben — kleine, einfache Datensätze ohne Verknüpfungen. Wie sich die Sync-API bei Produkten mit Übersetzungen, Preisen und Medien verhält, ist eine andere Frage, insbesondere was Laufzeit und Speicher betrifft.
Nicht gemessen wurde außerdem das Verhalten mehrerer Operationen im selben Aufruf — die Sync-API erlaubt es, in einem Aufruf zu schreiben und zu löschen. Ob sich das Alles-oder-nichts über alle Operationen erstreckt oder je Operation gilt, haben wir nicht geprüft und behaupten es deshalb nicht.
Die Testdatensätze wurden nach der Messung namentlich gelöscht; die Zieltabelle stand danach wieder bei drei Zeilen.
Häufige Fragen
- Verwirft die Sync-API wirklich den ganzen Stapel bei einem Fehler?
- Ja. Im Test blieb die Zieltabelle bei drei Zeilen, obwohl einer der beiden übergebenen Datensätze vollständig gültig war. Das ist beabsichtigtes Alles-oder-nichts.
- Ist upsert idempotent?
- Ja. Derselbe Aufruf ein zweites Mal liefert wieder HTTP 200 und ändert die Zeilenzahl nicht. Wer eine ID mitgibt, kann denselben Stapel gefahrlos wiederholen.
- Wie groß darf ein Stapel sein?
- Das hängt an PHP-Speicher, Laufzeitgrenze und der Größe der Datensätze, nicht an einer festen Zahl im Kern. In der Praxis sind einige hundert Datensätze je Aufruf ein guter Startwert, den man misst statt schätzt.
- Woran erkenne ich den fehlerhaften Datensatz?
- Am Fehlerzeiger in der Antwort. Er trägt den Schlüssel der Operation, den Index im Stapel und den Feldnamen — im Test /schreibe-steuern/1/taxRate für den zweiten Datensatz.