View a markdown version of this page

Demandes de requêtes pour Amazon EC2 - Amazon Elastic Compute Cloud
Structure d'une demande GETParamètres de requêteAuthentification par API de requêteStructures de réponse aux requêtesPaginationEmpêcher les requêtes via HTTP

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Demandes de requêtes pour Amazon EC2

Les requêtes de requête sont des requêtes HTTP ou HTTPS qui utilisent le verbe HTTP GET ou POST et un paramètre de requête nomméAction. Pour chaque action d'API Amazon EC2, vous pouvez choisir d'utiliser GET ou POST. Quel que soit le verbe que vous choisissez, les mêmes données sont envoyées et reçues. Pour obtenir la liste des actions de l'API Amazon EC2, consultez la section Actions.

Structure d'une demande GET

La documentation Amazon EC2 présente les requêtes GET sous forme d'URL, qui peuvent être utilisées directement dans un navigateur.

Note

Les requêtes GET étant des URL, vous devez encoder les valeurs des paramètres par URL. Dans la documentation Amazon EC2, nous laissons les exemples de requêtes GET non codés pour en faciliter la lecture.

La demande comprend les éléments suivants :

  • Point de terminaison  : URL qui sert de point d'entrée au service Web. Pour plus d'informations, consultez la section Points de terminaison de service Amazon EC2.

  • Action  : action que vous souhaitez effectuer ; par exemple, RunInstances pour lancer une instance.

  • Paramètres  : tous les paramètres de l'action ; chaque paramètre est séparé par une esperluette (&).

  • Version  : version de l'API à utiliser. Pour l'API Amazon EC2, la version est 2016-11-15.

  • Paramètres d'autorisation  : paramètres d'autorisation AWS utilisés pour garantir la validité et l'authenticité de la demande. Amazon EC2 prend en charge Signature Version 2 et Signature Version 4. Nous vous recommandons d'utiliser la version 4 de Signature. Pour plus d'informations, consultez la section Signer des demandes d' AWS API dans le guide de l'utilisateur IAM.

Les paramètres facultatifs suivants peuvent être inclus dans votre demande :

  • DryRun: vérifie si vous disposez des autorisations requises pour l'action, sans effectuer réellement la demande. Si vous disposez des autorisations requises, la demande est renvoyée DryRunOperation ; sinon, elle est renvoyéeUnauthorizedOperation.

  • SecurityToken: jeton de sécurité temporaire obtenu lors d'un appel à AWS Security Token Service.

Pour plus d'informations sur les paramètres courants pour les demandes d'API, consultez la section Paramètres de requête courants.

Voici un exemple de requête qui lance des instances :

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2016-11-15&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20130813%2Fus-east-1%2Fec2%2Faws4_request&X-Amz-Date=20130813T150206Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date&X-Amz-Signature=525d1a96c69b5549dd78dbbec8efe264102288b83ba87b7d58d4b76b71f59fd2
Content-type: application/json
host:ec2.amazonaws.com

Pour rendre ces exemples de demandes encore plus faciles à lire, AWS la documentation peut les présenter dans le format suivant :

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&Version=2016-11-15
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLEus-east-1%2Fec2%2Faws4_request
&X-Amz-Date=20130813T150206Z
&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date
&X-Amz-Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c
Content-type: application/json
host:ec2.amazonaws.com

La première ligne indique le point final de la demande. Le point d'extrémité est suivi d'un point d'interrogation (?), qui sert à l'isoler des paramètres. Pour plus d'informations sur les points de terminaison Amazon EC2, consultez la section Points de terminaison de service Amazon EC2.

Le paramètre Action indique l'action à exécuter. Pour une liste complète des actions, voir Actions. Les lignes restantes spécifient des paramètres supplémentaires pour la demande.

Dans les exemples de requêtes que nous présentons dans la documentation de l'API Amazon EC2, nous omettons les en-têtes, les paramètres obligatoires courants et les paramètres d'authentification pour vous permettre de vous concentrer plus facilement sur les paramètres de l'action. Nous les remplaçons par la chaîne &AUTHPARAMS littérale pour vous rappeler que vous devez inclure ces paramètres dans votre demande ; par exemple :

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&AUTHPARAMS
Important

Avant de spécifier l'ID de votre clé d'accès pour le Credential paramètre AWSAccessKeyId ou, consultez et suivez les instructions figurant dans les informations d'identification AWS de sécurité.

Paramètres de requête

Chaque demande de requête doit inclure les paramètres communs requis pour gérer l'authentification et la sélection d'une action. Les paramètres de requête distinguent les majuscules et minuscules.

Certaines actions demandent des listes de paramètres. Ces listes sont spécifiées à l'aide de la notation param.n, où n est un entier commençant à 1.

L'exemple suivant ajoute plusieurs appareils à un mappage de périphériques en mode bloc à l'aide d'une liste de BlockDeviceMapping paramètres.

http://ec2.amazonaws.com/?Action=RunInstances
&ImageId.1=ami-72aa081b
...
&BlockDeviceMapping.1.DeviceName=/dev/sdj
&BlockDeviceMapping.1.Ebs.NoDevice=true
&BlockDeviceMapping.2.DeviceName=/dev/sdh
&BlockDeviceMapping.2.Ebs.VolumeSize=300
&BlockDeviceMapping.3.DeviceName=/dev/sdc
&BlockDeviceMapping.3.VirtualName=ephemeral1
&AUTHPARAMS

Authentification par API de requête

Vous pouvez envoyer des requêtes Query via le protocole HTTP ou HTTPS.

Quel que soit le protocole que vous utilisez, vous devez inclure une signature dans chaque requête Query. Amazon EC2 prend en charge Signature Version 2 et Signature Version 4. Nous vous recommandons d'utiliser la version 4 de Signature. Pour plus d'informations, consultez la section Signer des demandes d' AWS API dans le guide de l'utilisateur IAM.

Les requêtes Signature Version 4 vous permettent de spécifier tous les paramètres d'autorisation dans un seul en-tête, par exemple :

Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Amz-Date: 20130813T150211Z
Host: ec2.amazonaws.com
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/202230813/us-east-1/ec2/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c

http://ec2.amazonaws.com/?Action=RunInstances
ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Monitoring.Enabled=true
&Placement.AvailabilityZone=us-east-1a
&Version=2016-11-15

Structures de réponse aux requêtes

En réponse à une demande de requête, le service renvoie une structure de données XML conforme à un schéma XML défini pour Amazon EC2. La structure d'une réponse XML est spécifique à la demande associée. En général, les types de données de réponse sont nommés en fonction de l'opération effectuée et selon que le type de données est un conteneur (peut avoir des enfants). Les exemples de conteneurs concernent groupSet les groupes de sécurité et keySet les paires de clés (voir l'exemple qui suit). Les éléments de l'article sont des enfants de conteneurs et leur contenu varie en fonction du rôle du conteneur.

Chaque réponse réussie inclut un ID de demande dans un requestId élément, et chaque réponse infructueuse inclut un ID de demande dans un RequestID élément. La valeur est une chaîne unique qui AWS attribue. Si vous rencontrez des problèmes avec une demande particulière, AWS nous vous demanderons l'identifiant de la demande pour vous aider à résoudre le problème. Voici un exemple de réponse.

<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
  <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
  <keySet>
    <item>
      <keyName>gsg-keypair</keyName>
      <keyFingerprint>
         00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
      </keyFingerprint>
    </item>
  </keySet>
</DescribeKeyPairsResponse>
Considérations

  • À compter du 31 juillet 2024, pour toute nouvelle action d'API Amazon EC2 ou toute nouvelle AWS région prise en charge, les structures de données XML des réponses n'incluront pas de nouvelles lignes ni d'indentations. Si vous utilisez un client personnalisé, assurez-vous qu'il ne repose pas sur les réponses, y compris les nouvelles lignes et les indentations.

  • À compter du 31 juillet 2025, les structures de données XML des réponses n'incluront plus de nouvelles lignes et de nouvelles indentations. Cette modification réduira la taille des réponses. Si vous utilisez un client personnalisé, assurez-vous qu'il ne repose pas sur les réponses, y compris les nouvelles lignes et les indentations.

  • L'ordre des éléments de la réponse, y compris ceux des structures imbriquées, peut varier. Les applications ne doivent pas partir du principe que les éléments apparaissent dans un ordre particulier.

Pagination

Pour les actions qui peuvent renvoyer une longue liste d'éléments, l'API Amazon EC2 inclut des paramètres permettant de prendre en charge la pagination :MaxResults, NextToken (entrée) et nextToken (sortie). Avec la pagination, vous spécifiez une taille pour, MaxResults puis chaque appel renvoie 0 aux MaxResults éléments et aux ensemblesnextToken. S'il y a des éléments supplémentaires à itérer, nextToken cette valeur n'est pas nulle et vous pouvez spécifier sa valeur dans le NextToken paramètre d'un appel ultérieur pour obtenir le prochain ensemble d'éléments. Avec la pagination, vous continuez à lancer l'action jusqu'à ce qu'elle nextToken soit nulle, même si vous recevez moins de MaxResults éléments, y compris aucun élément.

Si vous appelez une action d'API de description contenant à la fois une liste d'ID etMaxResults, la demande échoue avec le message d'erreurInvalidParameterCombination.

Nous vous recommandons d'utiliser la pagination lorsque vous utilisez des actions de description susceptibles de renvoyer un grand nombre de résultats, tels queDescribeInstances. L'utilisation de la pagination limite le nombre d'éléments renvoyés et le temps nécessaire au retour de ces appels.

Pour plus d'informations, consultez la section Pagination dans le guide du développeur Amazon EC2.

Empêcher les requêtes via HTTP

Si votre charge de travail ne nécessite pas que vous utilisiez le protocole HTTP, nous vous recommandons d'éviter de l'utiliser pour empêcher la transmission et la réception de données non chiffrées, et d'utiliser plutôt le protocole HTTPS. Vous pouvez utiliser la clé de condition IAM aws:SecureTransport globale dans vos politiques IAM pour empêcher les utilisateurs d'envoyer des requêtes via HTTP.

L'exemple de politique suivant empêche les utilisateurs d'envoyer des requêtes via HTTP.

{
    "Statement": [
        {
            "Sid": "AllowAllEC2HttpsRequests",
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*",
            "Condition": {
                "StringEqualsIgnoreCase": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}