Idempotente Anfragen
Idempotency-Key bei jedem Schreibzugriff senden, damit eine wiederholte Anfrage das erste Ergebnis liefert, statt dieselbe Änderung doppelt anzuwenden.
Ein Idempotency-Key kennzeichnet eine einzelne schreibende Anfrage. Wenn Sie dieselbe Anfrage mit demselben Schlüssel erneut senden, gibt die Plattform die Antwort auf die erste Anfrage zurück, statt die Änderung erneut auszuführen. So können Sie einen Schreibzugriff gefahrlos wiederholen, wenn Sie nicht wissen, ob er angekommen ist, z. B. nach einer Zeitüberschreitung oder einer abgebrochenen Verbindung.
Bei jedem Schreibzugriff einen Schlüssel senden
Senden Sie den Header Idempotency-Key bei jeder Anfrage mit POST, PUT, PATCH und DELETE. Verwenden Sie für jede neue Anfrage eine neue zufällige UUID:
KEY=$(uuidgen)
curl -X POST "https://<api-host>/api/v1/scopes/<project-id>/compute/instances/<instance-id>/actions/stop" \
-H "Authorization: Bearer $PC_TOKEN" \
-H "Idempotency-Key: $KEY"<api-host>,<project-id>,<instance-id>: der Hostname der API, die ID des Projekts und die ID der Instanz.KEY: der Schlüssel. Bewahren Sie ihn auf, bis Sie das Ergebnis kennen, damit eine Wiederholung denselben Wert senden kann.
Einige Vorgänge akzeptieren als Schlüssel nur eine UUID, z. B. die Vorgänge für Benutzer, Einladungen, Rollenzuweisungen, Dienstkonten und API-Tokens. Ein anderer Wert gibt 422 Unprocessable Entity mit dem Code VALIDATION_FAILED und dem Feld Idempotency-Key zurück.
Wichtig
Mit einem API-Token oder einem Dienstkontoschlüssel ist der Schlüssel bei jeder Anfrage mit POST erforderlich, die eine Ressource erstellt und mit 202 Accepted antwortet: z. B. beim Erstellen einer Instanz, eines Volumes, eines Netzwerks, einer Floating-IP, eines Load Balancers, eines Buckets, eines Snapshots, einer Rolle oder einer Verpflichtung, beim Klonen eines Volumes oder beim Wiederherstellen eines Snapshots in ein neues Volume. Ohne den Schlüssel wird eine solche Anfrage mit 400 Bad Request und dem Code IDEMPOTENCY_KEY_REQUIRED abgelehnt. Das API-Gateway vergibt dafür keinen eigenen Schlüssel, denn eine Wiederholung würde einen anderen Schlüssel erhalten und eine zweite Ressource erstellen. Die API-Referenz kennzeichnet den Header bei diesen Vorgängen als erforderlich.
Bei allen anderen Schreibzugriffen ist der Schlüssel optional: bei Anfragen mit DELETE, PATCH und PUT und bei Aktionen für eine bestehende Ressource, z. B. beim Starten einer Instanz oder beim Anhängen eines Volumes. Wenn Sie einen Schlüssel senden, antwortet die Plattform auf einen wiederholten Schlüssel wie unten beschrieben. Wenn nicht, wird die Anfrage einmal ohne Schutz vor Wiederholungen ausgeführt, und eine Wiederholung kann die Änderung erneut anwenden. Senden Sie auch bei diesen Schreibzugriffen einen Schlüssel, und erzeugen Sie ihn selbst, damit eine Wiederholung denselben Wert senden kann.
Antwort der Plattform auf einen wiederholten Schlüssel
Bei einem Vorgang, der den Schlüssel verwendet, vergleicht die Plattform einen wiederholten Schlüssel mit der Anfrage, die ihn zuerst verwendet hat. Zwei Anfragen sind gleich, wenn sie dieselbe Methode, denselben Pfad und denselben Body haben. Die Reihenfolge der Felder in einem JSON-Body spielt keine Rolle.
| Sie senden | Die Plattform antwortet |
|---|---|
| Denselben Schlüssel und dieselbe Anfrage, nachdem die erste Anfrage abgeschlossen ist | Mit Status und Body der ersten Antwort. Die Änderung wird nicht erneut ausgeführt. |
| Denselben Schlüssel und dieselbe Anfrage, während die erste Anfrage noch verarbeitet wird | Mit 409 Conflict und "retryable": true. Warten Sie einen Moment, und senden Sie die Anfrage mit demselben Schlüssel erneut. |
| Denselben Schlüssel mit einer anderen Anfrage | Mit 409 Conflict und dem Code CONFLICT. Verwenden Sie für eine neue Anfrage einen neuen Schlüssel. |
Einige Details zur Wiedergabe der ersten Antwort:
- Nur Status und Body. Eine Wiedergabe wiederholt Status und Body der ersten Antwort. Antwortheader der ersten Antwort, etwa
ETag, werden nicht wiederholt. - Geänderte Ressourcen. Die Wiedergabe erfolgt, bevor die Anfrage erneut geprüft wird, daher wird die erste Antwort auch dann zurückgegeben, wenn sich die Ressource inzwischen geändert hat. Zum Beispiel gibt ein wiederholtes Löschen einer bereits gelöschten Ressource die erste Antwort zurück, nicht
404 Not Found. - Unterbrochene Anfragen. Wenn die erste Anfrage während der Verarbeitung abgebrochen ist, können Wiederholungen mit ihrem Schlüssel bis zu 2 Minuten lang
409 Conflictmit"retryable": truezurückgeben.
Gültigkeitsdauer eines Schlüssels
Die Plattform bewahrt den Datensatz eines Schlüssels mindestens 24 Stunden nach der ersten Anfrage auf. Senden Sie Ihre Wiederholungen innerhalb von 24 Stunden.
Verwenden Sie den Schlüssel nach 24 Stunden nicht wieder. Je nach Vorgang lehnt die Plattform ihn dann mit 409 Conflict und einer Meldung ab, dass der Schlüssel abgelaufen ist, gibt die erste Antwort erneut zurück oder behandelt die Anfrage als neue Anfrage.
Vorgänge, die den Schlüssel nicht verwenden
Einige Vorgänge ignorieren den Schlüssel, und die API-Referenz führt den Header Idempotency-Key für sie nicht auf. Wenn Sie sie wiederholen, wird die Anfrage erneut ausgeführt, mit diesen Ergebnissen:
| Vorgang | Ergebnis einer Wiederholung |
|---|---|
| Aktualisieren einer Instanz, eines Volumes, eines Netzwerks, eines Subnetzes, eines Routers, einer Netzwerkschnittstelle oder einer Sicherheitsgruppe | Diese Aktualisierungen erfordern If-Match. Wurde die erste Aktualisierung angewendet, gibt die Wiederholung 412 Precondition Failed zurück, weil sich die Version geändert hat. Lesen Sie die Ressource, um das Ergebnis zu prüfen. |
| Ersetzen der Tags einer Instanz, eines Volumes, eines Abbilds oder eines Instanz-Snapshots | Dieselben Tags werden erneut gesetzt. Wenn Sie If-Match gesendet haben, gibt die Wiederholung 412 Precondition Failed zurück. |
| Erneuern des Signaturgeheimnisses eines Benachrichtigungskanals oder des Temp-URL-Schlüssels von Object Storage | Das Geheimnis bzw. der Schlüssel wird ein zweites Mal erneuert. |
| Senden einer Testbenachrichtigung oder einer Bestätigungs-E-Mail für einen Benachrichtigungskanal | Die Nachricht wird erneut gesendet. |
Schreibzugriff sicher wiederholen
- Erzeugen Sie eine UUID, bevor Sie den Schreibzugriff senden, und speichern Sie sie mit der Anfrage.
- Wenn bei der Anfrage eine Zeitüberschreitung auftritt, die Verbindung abbricht oder Sie
429 Too Many Requestsoder einen Status5xxerhalten, senden Sie dieselbe Anfrage mit demselben Schlüssel. - Wenn Sie
409 Conflictmit"retryable": trueerhalten, warten Sie, und senden Sie sie mit demselben Schlüssel erneut. - Wenn Sie das Ergebnis haben, verwenden Sie für Ihre nächste Anfrage einen neuen Schlüssel, auch wenn diese Anfrage identisch ist. Zum Beispiel braucht das Erstellen einer zweiten, identischen Instanz einen eigenen Schlüssel.
Warten Sie zwischen Wiederholungen zunehmend länger. Warten Sie nach einer Antwort 429 Too Many Requests mindestens die Anzahl der Sekunden aus ihrem Header Retry-After. Bevor Sie einen Vorgang wiederholen, der den Schlüssel nicht verwendet, prüfen Sie, ob die erste Anfrage angewendet wurde. Die Statuscodes finden Sie unter Fehler.