| « PreviousNext » | |
   | Did this page help you? Yes | No | Tell us about it... |
Query Requests
Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a
Query parameter named Action. For a list of Amazon EC2 API actions, see Actions.
Topics
Structure of a GET Request
The Amazon EC2 documentation presents the GET requests as URLs, which can be used directly in a browser.
Tip
Because the GET requests are URLs, you must URL encode the parameter values. In the Amazon EC2 documentation, we leave the example GET requests unencoded to make them easier to read.
The URL consists of the following:
- Endpoint
The URL that serves as the entry point for the web service
- Action
The action that you want to perform (for example, use
RunInstanceto run an instance)- Parameters
Any parameters for the request; each parameter is separated by an ampersand (&).
The following is an example request that launches instances.
https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-60a54009&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1b&Monitoring.Enabled=true&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Version=2013-02-01&Expires=2010-10-10T12:00:00Z&Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE&SignatureVersion=2&SignatureMethod=HmacSHA256
To make these example requests even easier to read, the Amazon EC2 documentation presents them in the following format.
https://ec2.amazonaws.com/?Action=RunInstances &ImageId=ami-60a54009 &MaxCount=3 &MinCount=1 &Placement.AvailabilityZone=us-east-1b &Monitoring.Enabled=true &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &Version=2013-02-01 &Expires=2010-10-10T12:00:00Z &Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE &SignatureVersion=2 &SignatureMethod=HmacSHA256
The first line specifies the endpoint of the request. After the endpoint is a question mark (?), which separates the endpoint from the parameters.
The Action parameter indicates the action to perform. For a complete
list of actions, see Actions in
the Amazon Elastic Compute Cloud API Reference.
The remaining lines specify additional parameters for the request.
Query Parameters
Each Query request must include required common parameters to handle authentication and selection of an action. For more information, see Common Query Parameters in the Amazon Elastic Compute Cloud API Reference.
Some operations take lists of parameters. These lists are specified using the param.n notation, where n is an integer starting from 1.
The following example adds multiple devices to a block device mapping using a list
of BlockDeviceMapping parameters.
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
Query API Authentication
You can send Query requests over either HTTP or HTTPS. Regardless of which protocol you use, you must include a signature in every Query request. Amazon EC2 uses Signature Version 2. For more information, see Signature Version 2 Signing Process in the Amazon Web Services General Reference.
Tip
In the example Query requests we present in the Amazon EC2 documentation, we
omit the parameters related to authentication to make it easier for you to focus
on the parameters for the action. We replace them with the following literal
string to remind you that you must include these parameters in your request:
&AuthParams.
Query Response Structures
In response to a Query request, the service returns an XML data structure that
conforms to an XML schema defined as part of the WSDL
file for Amazon EC2. The structure of an XML response is specific to the associated
request. In general, the response data types are named according to the operation
performed and whether the data type is a container (can have children). Examples of
containers include groupSet for security groups and keySet
for key pairs (see the example that follows). Item elements are children of
containers, and their contents vary according to the container's role.
Every response includes a request ID in a requestId element. The
value is a unique string that AWS assigns. If you ever have issues with a particular
request, AWS will ask for the request ID to help troubleshoot the issue. The
following shows an example response.
<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
<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>Query API Request Rate
We throttle Amazon EC2 API requests for each AWS account to help the performance of the service. We ensure that all calls to the Amazon EC2 API (whether they originate from an application, calls to the Amazon EC2 command line interface, or the Amazon EC2 console) don't exceed the maximum allowed API request rate. Note that API requests made by IAM users are attributed to the underlying AWS account.
The Amazon EC2 API actions are divided into the following categories:
Describe actions, such as
DescribeInstancesandDescribeVolumes. These requests simply retrieve cached data, so they have the highest request limit.Modify actions, such as
RunInstancesandCreateVolumes. These requests create or modify resources, so they have a lower request limit than describe calls.The
CreateKeyPair,GetConsoleOutputAuthorizeSecurityGroupIngress, andRevokeSecurityGroupIngressactions. These requests take the most time and resource to complete, so they have the lowest request limit.
If an API request exceeds the API request rate for its category, the request
returns the RequestLimitExceeded error code. To prevent this error,
ensure that your application doesn't retry API requests at a high rate. You can do
this by using care when polling and by using exponential back-off retries.
Polling
Your application might need to call an API repeatedly to check for an update in status. Before you start polling, give the request time to potentially complete. When you begin polling, use an appropriate sleep interval between successive requests. For best results, use an increasing sleep interval.
Retries or batch processing
Your application might need to retry an API request after it fails, or to process multiple resources (for example, all your volumes). To lower the rate of API requests, use an appropriate sleep interval between successive requests. For best results, use an increasing or variable sleep interval.
Eventual Consistency
The Amazon EC2 API follows an eventual consistency model, due to the distributed nature of the system supporting the API. This means that the result of an API command you run that affects your Amazon EC2 resources might not be immediately visible to subsequent commands you run. You should keep this in mind when you carry out an API command that immediately follows a previous API command.
Eventual consistency can affect the way you manage your resources. For example, if you run a command to create a resource, it will eventually be visible to other commands. This means that if you run a command to modify or describe the resource that you just created, its ID might not have propagated throughout the system, and you will get an error responding that the resource does not exist.
To manage eventual consistency, you can do the following:
Confirm the state of the resource before you run a command to modify it. To do this, run the appropriate
Describecommand.Run the appropriate
Describecommand using an exponential back-off algorithm to ensure that you allow enough time for the previous command to propagate through the system. To do this, run theDescribecommand repeatedly, starting with a couple of seconds of wait time, and increasing gradually up to about a minute of wait time. This should ensure that theDescribecommand eventually returns an accurate result.
Eventual Consistency Error Examples
The following are examples of error codes you may encounter as a result of eventual consistency.
InvalidInstanceID.NotFoundIf you successfully carry out the
RunInstancescommand, and run a command directly afterwards using the instance ID that was provided in the response ofRunInstances, it may return anInvalidInstanceID.NotFounderror. This does not mean the instance does not exist.Some specific commands that may be affected are:
DescribeInstances: To confirm the actual state of the instance, run this command using an exponential back-off algorithm.TerminateInstances: To confirm the state of the instance, first run theDescribeInstancescommand using an exponential back-off algorithm.Important
If you get an
InvalidInstanceID.NotFounderror after runningTerminateInstances, this does not mean that the instance is or will be terminated. Your instance could still be running. This is why it is important to first confirm the instance’s state usingDescribeInstances.
InvalidGroup.NotFoundIf you successfully carry out the
CreateSecurityGroupcommand, and run a command directly afterwards using the instance ID that was provided in the response ofCreateSecurityGroup, it may return anInvalidGroup.NotFounderror. To confirm the state of the security group, run theDescribeSecurityGroupscommand using an exponential back-off algorithm.
