Sicherstellung der Idempotenz bei Amazon-Anfragen EC2 API

Wenn Sie eine mutierende API Anfrage stellen, gibt die Anfrage in der Regel ein Ergebnis zurück, bevor die asynchronen Workflows des Vorgangs abgeschlossen sind. Es können auch ein Timeout oder andere Serverprobleme auftreten, bevor Operationen abgeschlossen sind, obwohl die Anfrage bereits ein Ergebnis zurückgegeben hat. Dadurch lässt sich möglicherweise nur schwer feststellen, ob die Anfrage erfolgreich war oder nicht, und es werden möglicherweise mehrere Wiederholungsversuche vorgenommen, um sicherzustellen, dass die Operation erfolgreich abgeschlossen wird. Wenn die ursprüngliche Anfrage und die nachfolgenden Wiederholungsversuche jedoch erfolgreich sind, wird die Operation mehrmals abgeschlossen. Das bedeutet, dass Sie möglicherweise mehr Ressourcen erstellen, als Sie beabsichtigt haben.

Idempotenz stellt sicher, dass eine API Anfrage nicht öfter als einmal abgeschlossen wird. Wenn bei einer idempotenten Anfrage die ursprüngliche Anfrage erfolgreich abgeschlossen wird, werden alle nachfolgenden Wiederholungen erfolgreich abgeschlossen, ohne dass weitere Aktionen ausgeführt werden. Das Ergebnis kann jedoch aktualisierte Informationen enthalten, z. B. den aktuellen Erstellungsstatus.

Idempotenz bei Amazon EC2

Die folgenden API Aktionen sind standardmäßig idempotent und erfordern keine zusätzliche Konfiguration. Die entsprechenden AWS CLI Befehle unterstützen standardmäßig auch Idempotenz.

Die folgenden API Aktionen unterstützen optional Idempotenz mithilfe eines Client-Tokens. Die entsprechenden AWS CLI Befehle unterstützen auch Idempotenz mithilfe eines Client-Tokens. Ein Client-Token ist eine eindeutige Zeichenfolge mit bis zu 64 Zeichen, bei der Groß- und Kleinschreibung beachtet wird. ASCII Um mit einer dieser Aktionen eine idempotente API Anfrage zu stellen, geben Sie in der Anfrage ein Client-Token an. Sie sollten dasselbe Client-Token nicht für andere API Anfragen wiederverwenden. Wenn Sie eine Anfrage, die erfolgreich abgeschlossen wurde, mit demselben Client-Token und denselben Parametern erneut versuchen, ist die Wiederholung erfolgreich, ohne dass weitere Aktionen ausgeführt werden. Wenn Sie eine erfolgreiche Anfrage mit demselben Client-Token erneut versuchen, aber einer oder mehrere der Parameter anders sind als die Region oder Availability Zone, schlägt die Wiederholung mit einem Fehler fehl. IdempotentParameterMismatch

RunInstances Idempotenz

Die RunInstancesAPIAktion nutzt sowohl regionale als auch zonale Idempotenz.

Die Art der verwendeten Idempotenz hängt davon ab, wie Sie die Availability Zone in Ihrer Anfrage angeben. RunInstances API Die Anfrage verwendet in den folgenden Fällen zonale Idempotenz:

Wenn Sie keine Availability Zone explizit oder implizit angeben, verwendet die Anfrage regionale Idempotenz.

Zonale Idempotenz

Die zonale Idempotenz stellt sicher, dass eine RunInstances API Anfrage in jeder Availability Zone in einer Region idempotent ist. Dadurch wird sichergestellt, dass eine Anfrage mit demselben Client-Token innerhalb jeder Availability Zone in einer Region nur einmal abgeschlossen werden kann. Dasselbe Client-Token kann jedoch verwendet werden, um Instances in anderen Availability Zones in der Region zu starten.

Wenn Sie beispielsweise eine idempotente Anfrage senden, um eine Instance in der us-east-1a Availability Zone zu starten, und dann dasselbe Client-Token in einer Anfrage in der us-east-1b Availability Zone verwenden, starten wir Instances in jeder dieser Availability Zones. Wenn einer oder mehrere der Parameter unterschiedlich sind, kehren nachfolgende Wiederholungen mit demselben Client-Token in diesen Availability Zones entweder erfolgreich zurück, ohne dass weitere Aktionen ausgeführt werden, oder schlagen mit einem Fehler fehl. IdempotentParameterMismatch

Regionale Idempotenz

Regionale Idempotenz stellt sicher, dass eine RunInstances API Anfrage in einer Region idempotent ist. Dadurch wird sichergestellt, dass eine Anfrage mit demselben Client-Token innerhalb einer Region nur einmal abgeschlossen werden kann. Genau dieselbe Anfrage mit demselben Client-Token kann jedoch verwendet werden, um Instances in einer anderen Region zu starten.

Wenn Sie beispielsweise eine idempotente Anfrage senden, um eine Instance in der us-east-1 Region zu starten, und dann dasselbe Client-Token in einer Anfrage in der eu-west-1 Region verwenden, starten wir Instances in jeder dieser Regionen. Wenn einer oder mehrere der Parameter unterschiedlich sind, kehren nachfolgende Wiederholungen mit demselben Client-Token in diesen Regionen entweder erfolgreich zurück, ohne dass weitere Aktionen ausgeführt werden, oder schlagen mit einem Fehler fehl. IdempotentParameterMismatch

Beispiele

AWS CLI Beispiele für Befehle

Um einen AWS CLI Befehl idempotent zu machen, fügen Sie die --client-token Option hinzu.

Beispiel 1: Idempotenz

Der folgende Befehl allocate-hosts verwendet Idempotenz, da er ein Client-Token enthält.

aws ec2 allocate-hosts  --instance-type m5.large  --availability-zone eu-west-1a  --auto-placement on  --quantity 1 --client-token 550e8400-e29b-41d4-a716-446655440000

Beispiel 2: Regionale Idempotenz von Run-Instances

Der folgende Befehl run-instances verwendet regionale Idempotenz, da er ein Client-Token beinhaltet, aber weder explizit noch implizit eine Availability Zone spezifiziert.

aws ec2 run-instances --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

Beispiel 3: Zonale Idempotenz von Run-Instances

Der folgende Befehl run-instances verwendet zonale Idempotenz, da er ein Client-Token und eine explizit angegebene Availability Zone enthält.

aws ec2 run-instances  --placement "AvailabilityZone=us-east-1a" --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

APIBeispiele anfordern

Um eine API Anfrage idempotent zu machen, fügen Sie den ClientToken Parameter hinzu.

Beispiel 1: Idempotenz

Die folgende AllocateHostsAPIAnfrage verwendet Idempotenz, da sie ein Client-Token enthält.

https://ec2.amazonaws.com/?Action=AllocateHosts
&AvailabilityZone=us-east-1b
&InstanceType=m5.large
&Quantity=1
&AutoPlacement=off
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Beispiel 2: regionale Idempotenz RunInstances

Die folgende RunInstancesAPIAnfrage verwendet regionale Idempotenz, da sie ein Client-Token enthält, aber weder explizit noch implizit eine Availability Zone spezifiziert.

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Beispiel 3: Zonale Idempotenz RunInstances

Die folgende RunInstancesAPIAnfrage verwendet zonale Idempotenz, da sie ein Client-Token und eine explizit angegebene Availability Zone enthält.

https://ec2.amazonaws.com/?Action=RunInstances
&Placement.AvailabilityZone=us-east-1d
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Versuchen Sie es erneut mit Empfehlungen für idempotente Anfragen

Die folgende Tabelle zeigt einige häufig auftretende Antworten auf idempotente API Anfragen und enthält Empfehlungen für Wiederholungen.