Bulk-Endpunkte und die Meldung teilweiser Fehlschläge

Worum es geht

Ein Bulk-Endpunkt nimmt viele Elemente in einer Anfrage entgegen: 500 Kontakte erstellen, 50 Preise aktualisieren, oder, wie beim JSON-Batching von Microsoft Graph (zitiert), bis zu 20 beliebige Teilanfragen in einem einzigen HTTP-Aufruf bündeln. Es gibt zwei Verhaltensweisen. Atomar: Entweder werden alle Elemente angewendet oder keines. Teilerfolg: Der Server wendet an, was er kann, und meldet jeden Fehlschlag einzeln. Googles AIP-233 (zitiert) verlangt, dass ein synchrones Batch-Create atomar ist, und dessen Begründung erklärt weshalb: Ein OK-Status impliziert, dass alles funktioniert hat; würde man einer synchronen Antwort später Informationen über Teilfehlschläge hinzufügen, würde das stillschweigend ändern, wovon bestehende Clients ausgehen. Asynchrone Batches, die eine Operation zurückgeben, können Teilerfolg unterstützen und Fehlschläge als Abbildung vom Anfrageindex auf ein Statusobjekt melden; vorübergehende Fehler, die der Server erneut versuchen wird, dürfen dort nicht auftauchen, und wenn jedes Element scheitert, wird die Operation selbst als fehlgeschlagen markiert.

Warum es wichtig ist

Clients wiederholen Bulk-Anfragen. Bei atomarer Semantik ist eine Wiederholung sicher; bei Teilerfolg reicht eine Wiederholung bereits angewendete Elemente erneut ein, sofern der Client nicht erkennen kann, welche gescheitert sind. Das Meldeformat entscheidet, ob Wiederholungen Duplikate erzeugen.

So wird es angewendet

• Pro Endpunkt ein Verhalten festlegen, es dokumentieren und nie stillschweigend ändern; der Wechsel von atomar zu Teilerfolg braucht eine neue Version oder ein explizites Flag, das standardmässig das alte Verhalten beibehält (AIP-233 beschreibt return_partial_success).
• Den Status auf Anfrageebene getrennt von den Ergebnissen pro Element melden. Graph gibt für jeden parsebaren Batch 200 zurück, versieht jede Teilantwort mit einem eigenen status und hält fest, dass ein 200 auf den Batch nicht bedeutet, dass die einzelnen Anfragen erfolgreich waren.
• Fehlschläge nach Index oder nach einer vom Client mitgelieferten, innerhalb des Batches eindeutigen ID adressieren, und dieselbe Fehlerform wie bei einem einzelnen Element wiederverwenden, damit sich Client-Codepfade teilen lassen.
• Die Batchgrösse begrenzen und die Grenze dokumentieren. Autorisierung, Validierung und Ratenbegrenzung pro Element durchsetzen; Graph bewertet jede Anfrage einzeln gegenüber Drosselung und lässt diese Anfrage mit 429 scheitern.
• Reihenfolge nur unterstützen, wenn nötig; Graphs dependsOn lässt abhängige Anfragen mit 424 (Failed Dependency) scheitern, wenn eine Voraussetzung fehlschlägt.
• WebDAVs 207 (Multi-Status) (RFC 4918, zitiert) existiert für mehrere Status pro Ressource, aber allgemeine Clients und Proxys kennen es nicht; ein JSON-Body mit Status pro Element ist portabler.

Stolpersteine

Ein Teilerfolgs-Endpunkt, der ein blosses 200 zurückgibt und Fehlschläge in einem Log vergräbt. Anfrage-Payloads in Fehlereinträgen zurückzuspiegeln, was AIP-233 aus Gründen der Datenempfindlichkeit ablehnt. Batches, deren Verarbeitung das Gateway-Timeout überschreitet: Ab einer gewissen Grösse gehört Bulk-Arbeit in eine lang laufende Operation.