Idempotency-Key-Header
Mit Idempotency-Key können Sie eine Anfrage erneut versuchen, ohne eine doppelte Operation zu erzeugen. Die Garantie lautet genau einmalige Annahme: Innerhalb des Aufbewahrungszeitraums von 3 Stunden müssen erneute Versuche mit demselben Key und identischer Anfrage zur ursprünglichen Operation führen, auch wenn Ihnen deren Antwort verloren gegangen ist. Hinweise zur Strategie für erneute Versuche finden Sie unter Idempotenz.
Request-Header
| Header | Einschränkungen |
|---|---|
Idempotency-Key | Optional. Eine beliebige, nicht leere Zeichenfolge mit bis zu 255 Zeichen; empfohlen wird eine UUID v4. Wird bei unterstützten POST-, PATCH-, PUT- und DELETE-Operationen berücksichtigt; bei GET, HEAD und OPTIONS ignoriert. |
Mutationen im Geltungsbereich eines Workspace oder einer Organisation unterstützen die unten beschriebene Wiedergabe gespeicherter Antworten. Operationen, die ausschließlich einem Benutzer zugeordnet sind, nicht authentifizierte Operationen ohne Geltungsbereich und Streams nutzen sie nicht. Operationen mit einem eigenen Wiedergabevertrag beschreiben ihr Verhalten auf ihrer Referenzseite.
Wenn Sie den Header weglassen oder einen leeren Wert senden, wird die Anfrage normal und ohne Deduplizierung verarbeitet. Bei Endpunkten, die diesen Header deklarieren, führt ein Schlüssel mit mehr als 255 Zeichen zu 422 mit dem Code E01001 ValidationError.
Schlüssel gelten für Ihren Workspace oder bei Endpunkten auf Organisationsebene für Ihre Organisation und werden ungefähr 3 Stunden gespeichert. Nach Ablauf dieses Zeitraums wird eine Anfrage mit einem erneut verwendeten Schlüssel als neue Anfrage verarbeitet.
Response-Semantik
| Szenario | Response |
|---|---|
| Erste Anfrage mit einem Key | Wird normal verarbeitet; eine abgeschlossene Antwort kann zur Wiedergabe gespeichert werden; 5xx-Antworten werden nicht gespeichert. |
| Gleicher Key, identische Anfrage innerhalb der Aufbewahrung | Die ursprüngliche Operation; eine gespeicherte Antwort wird mit Idempotency-Replay: true wiedergegeben. |
| Gleicher Key, andere Anfrage | 409 mit E01005 IdempotencyKeyReuse. Generieren Sie einen neuen Key für die neue Anfrage. |
| Gleicher Key, ursprüngliche Anfrage noch in Bearbeitung | 409 mit E01004 RequestInProgress. Warten Sie und versuchen Sie es mit demselben Key und identischer Anfrage erneut. |
Ursprüngliche Anfrage lieferte 5xx zurück | Die Fehlerantwort wird nicht gespeichert. Versuchen Sie es mit demselben Key und identischer Anfrage erneut. |
| Idempotenzschutz vor Ausführung nicht verfügbar | 503 mit E01033 IdempotencyUnavailable. Dieser Versuch wird nicht ausgeführt; mit demselben Key und derselben Anfrage erneut versuchen. |
Eine wiedergegebene Response ist Byte für Byte das Original (gleicher Statuscode, gleicher Body), unterschieden nur durch den zusätzlichen Header:
HTTP/1.1 202 Accepted
Idempotency-Replay: true"Identical request" umfasst Methode, Endpunkt, Pfad- und Abfrageparameter sowie den unveränderten Anfrageinhalt. Unterschiede in diesen Werten, einschließlich Leerraum in JSON, lösen E01005 aus. Bei Multipart-Uploads werden Teilnamen, Dateinamen und Inhalte verglichen; Grenzen und Reihenfolge der Teile beeinflussen die Wiedergabe nicht. Beide 409-Fehler werden im Standardformat der Fehlerantwort zurückgegeben.
Gespeicherte Antworten können 4xx-Ablehnungen enthalten. Verwenden Sie beim Korrigieren einer Anfrage einen neuen Schlüssel: Wurde die Ablehnung gespeichert, gibt ein unveränderter Wiederholungsversuch sie erneut zurück; eine geänderte Anfrage führt zu 409 E01005 IdempotencyKeyReuse.
Versuchen Sie es nach einem Timeout oder 5xx innerhalb von drei Stunden mit begrenztem Backoff erneut, mit dem selben Key und identischer Anfrage. Die Garantie der genau einmaligen Annahme gilt auch, wenn die ursprüngliche Antwort verloren gegangen ist. E01033 IdempotencyUnavailable bedeutet, dass dieser Versuch nicht ausgeführt wurde; es beschreibt nicht das Ergebnis eines früheren Versuchs. Behalten Sie den Key bei jedem erneuten Versuch bei.
Beim Senden einer Nachricht bedeutet genau einmalige Annahme, dass über alle passenden erneuten Versuche hinweg genau ein Sendevorgang angenommen wird. Prüfen Sie den Nachrichtenstatus, um die Zustellung zu bestätigen. Prüfen Sie nach drei Stunden das Ergebnis der ursprünglichen Operation, bevor Sie erneut senden: Ein abgelaufener oder neuer Key kann eine weitere Operation erzeugen.
Verhalten der SDK
Die offiziellen SDKs hängen an jede mutierende Anfrage eine automatisch generierte UUID Idempotency-Key an. Sie wird einmal pro logischem Aufruf erzeugt und für alle erneuten Versuche dieses Aufrufs wiederverwendet. Sie können pro Aufruf einen eigenen Key angeben (idempotencyKey in TypeScript, option.WithIdempotencyKey in Go, idempotency_key in Python, new RequestOptions(idempotencyKey: ...) in PHP), wenn eine logische Operation mehrere SDK-Aufrufe umfasst. Um ein Replay zu erkennen, lesen Sie den Idempotency-Replay-Response-Header über den Transport-Metadata-Accessor jedes SDK: .withResponse() in TypeScript, option.WithResponseInto in Go und with_raw_response in Python.
Verwandte Themen
- Idempotenzkonzepte: Strategie für erneute Versuche, Key-Design und Replay-Limits
- Fehlerantworten: die Hülle um
E01004undE01005 - E-Mail-Nachrichten: der Send-Endpunkt, der häufigste Anwendungsfall für einen Key
- SDK-Konzepte: automatische Key-Generierung und Retries
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.