Garantir l'idempuissance des demandes Amazon EC2 API

Lorsque vous faites une API demande mutante, celle-ci renvoie généralement un résultat avant la fin des flux de travail asynchrones de l'opération. Les opérations peuvent également expirer ou rencontrer d’autres problèmes de serveur avant d’être terminées, même si la demande a déjà renvoyé un résultat. Par conséquent, il peut être difficile de déterminer si la demande a abouti ou non et de multiples tentatives peuvent être déclenchées pour s’assurer que l’opération se termine correctement. Toutefois, si la demande initiale et les tentatives suivantes aboutissent, l’opération est terminée plusieurs fois. Cela signifie que vous pourriez créer plus de ressources que prévu.

L'idempotencie garantit qu'une API demande ne sera traitée qu'une seule fois. Avec une demande idempotente, si la demande d’origine se termine avec succès, toutes les tentatives suivantes se terminent avec succès, sans aucune action supplémentaire. Cependant, le résultat peut contenir des informations mises à jour, telles que le statut de création actuel.

Idempotencia sur Amazon EC2

Les API actions suivantes sont idempotentes par défaut et ne nécessitent aucune configuration supplémentaire. Les AWS CLI commandes correspondantes prennent également en charge l'idempotencie par défaut.

Les API actions suivantes prennent éventuellement en charge l'idempotencie à l'aide d'un jeton client. Les AWS CLI commandes correspondantes prennent également en charge l'idempotencie à l'aide d'un jeton client. Un jeton client est une chaîne unique, distinguant majuscules et minuscules, de 64 ASCII caractères maximum. Pour effectuer une API demande idempotente à l'aide de l'une de ces actions, spécifiez un jeton client dans la demande. Vous ne devez pas réutiliser le même jeton client pour d'autres API demandes. Si vous réessayez une demande qui s'est terminée avec succès en utilisant le même jeton client et les mêmes paramètres, la nouvelle tentative aboutit sans effectuer d'autre action. Si vous réessayez une demande réussie en utilisant le même jeton client, mais qu'un ou plusieurs paramètres sont différents, autres que la région ou la zone de disponibilité, la nouvelle tentative échoue avec une IdempotentParameterMismatch erreur.

RunInstances idempuissance

L'RunInstancesAPIaction utilise à la fois l'idempuissance régionale et zonale.

Le type d'idempuissance utilisé dépend de la manière dont vous spécifiez la zone de disponibilité dans votre RunInstances API demande. La demande utilise l'idempotencie zonale dans les cas suivants :

Si vous ne spécifiez pas explicitement ou implicitement de zone de disponibilité, la demande utilise l'idempotencie régionale.

Idempotencie zonale

L'idempotencie zonale garantit qu'une RunInstances API demande est idempotente dans chaque zone de disponibilité d'une région. Cela garantit qu'une demande avec le même jeton client ne peut être traitée qu'une seule fois dans chaque zone de disponibilité d'une région. Toutefois, le même jeton client peut être utilisé pour lancer des instances dans d'autres zones de disponibilité de la région.

Par exemple, si vous envoyez une demande idempotente pour lancer une instance dans la zone de us-east-1a disponibilité, puis que vous utilisez le même jeton client dans une demande dans la zone de us-east-1b disponibilité, nous lançons des instances dans chacune de ces zones de disponibilité. Si un ou plusieurs paramètres sont différents, les tentatives suivantes avec le même jeton client dans ces zones de disponibilité sont soit renvoyées avec succès sans effectuer aucune autre action, soit échouer avec une IdempotentParameterMismatch erreur.

Idempuissance régionale

L'idempuissance régionale garantit qu'une RunInstances API demande est idempotente dans une région. Cela garantit qu'une demande avec le même jeton client ne peut être traitée qu'une seule fois dans une région. Cependant, la même demande, avec le même jeton client, peut être utilisée pour lancer des instances dans une autre région.

Par exemple, si vous envoyez une demande idempotente pour lancer une instance dans la us-east-1 région, puis que vous utilisez le même jeton client dans une demande dans la eu-west-1 région, nous lançons des instances dans chacune de ces régions. Si un ou plusieurs paramètres sont différents, les tentatives suivantes avec le même jeton client dans ces régions sont soit renvoyées avec succès sans effectuer aucune autre action, soit échouer avec une IdempotentParameterMismatch erreur.

Exemples

AWS CLI exemples de commandes

Pour rendre une AWS CLI commande idempotente, ajoutez l'--client-tokenoption.

Exemple 1 : Idempotencie

La commande allocate-hosts suivante utilise l'idempotencie car elle inclut un jeton client.

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

Exemple 2 : idempotence régionale des instances d'exécution

La commande run-instances suivante utilise l'idempotencie régionale car elle inclut un jeton client mais ne spécifie pas explicitement ou implicitement de zone de disponibilité.

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

Exemple 3 : idempotencie zonale des instances d'exécution

La commande run-instances suivante utilise l'idempotencie zonale car elle inclut un jeton client et une zone de disponibilité explicitement spécifiée.

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

APIexemples de demandes

Pour rendre une API requête idempotente, ajoutez le ClientToken paramètre.

Exemple 1 : Idempotencie

La AllocateHostsAPIdemande suivante utilise l'idempotencie car elle inclut un jeton client.

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

Exemple 2 : RunInstances idempuissance régionale

La RunInstancesAPIdemande suivante utilise l'idempotencie régionale car elle inclut un jeton client mais ne spécifie pas explicitement ou implicitement de zone de disponibilité.

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

Exemple 3 : idempotence RunInstances zonale

La RunInstancesAPIdemande suivante utilise l'idempotencie zonale car elle inclut un jeton client et une zone de disponibilité explicitement spécifiée.

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

Recommandations de nouvelle tentative pour les demandes idempotentes

Le tableau suivant présente certaines réponses courantes que vous pouvez obtenir pour les API requêtes idempotentes et fournit des recommandations pour réessayer.