View a markdown version of this page

Demandes de requête pour Amazon EC2 - Amazon Elastic Compute Cloud
Structure d'une demande GETParamètres Query (Requête)Authentification 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ête pour Amazon EC2

Les requêtes 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, les exemples de requêtes GET ne sont pas 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 du 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 le 15 novembre 2016.

  • 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 les versions 2 et 4 de Signature. Nous vous recommandons d'utiliser la version 4 de Signature. Pour plus d'informations, consultez la section Signature des demandes AWS d'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 réellement en faire la demande. Si vous disposez des autorisations requises, la demande est renvoyée DryRunOperation ; dans le cas contraire, elle est renvoyéeUnauthorizedOperation.

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

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

Voici un exemple de demande 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 afin de vous permettre de vous concentrer plus facilement sur les paramètres de l'action. Nous les remplaçons par une 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 Query (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 via le protocole HTTP ou HTTPS.

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

Les demandes 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 du fait que le type de données est un conteneur (peut avoir des enfants). Des exemples de conteneurs incluent groupSet les groupes de sécurité et keySet les paires de clés (voir l'exemple ci-dessous). Les éléments de l'article sont des enfants de contenants, et leur contenu varie en fonction du rôle du contenant.

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 affecte. Si vous rencontrez des problèmes avec une demande particulière, nous vous AWS demanderons l'ID 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 les nouvelles actions de l'API Amazon EC2 ou les nouvelles AWS régions prises en charge, les structures de données XML contenues dans les réponses n'incluront pas de nouvelles lignes ni de nouvelles indentations. Si vous utilisez un client personnalisé, assurez-vous qu'il ne repose pas sur les réponses, notamment 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 ni d'indentations. Ce changement réduira la taille des réponses. Si vous utilisez un client personnalisé, assurez-vous qu'il ne repose pas sur les réponses, notamment 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, il nextToken n'est pas nul et vous pouvez spécifier sa valeur dans le NextToken paramètre d'un appel suivant pour obtenir le prochain ensemble d'éléments. Avec la pagination, vous continuez à appeler l'action jusqu'à ce qu'elle nextToken soit nulle, même si vous recevez moins d'MaxResultséléments, y compris aucun élément.

Si vous appelez une action d'API de description avec à la fois une liste d'identifiants et une liste d'identifiantsMaxResults, la demande échoue avec l'erreurInvalidParameterCombination.

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

Pour plus d'informations, consultez la section Pagination dans le manuel Amazon EC2 Developer Guide.

Empêcher les requêtes via HTTP

Si votre charge de travail ne vous oblige pas à utiliser 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:SecureTransportglobale dans vos politiques IAM pour empêcher les utilisateurs d'envoyer des demandes via HTTP.

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

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