Amazon Elastic Compute Cloud
User Guide (API Version 2014-06-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.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.

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 request 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 RunInstance to run an instance).

  • Parameters: Any parameters for the action; each parameter is separated by an ampersand (&). You must also include authorization parameters that AWS uses to ensure the validity and authenticity of the request. Amazon EC2 supports Signature Version 2 and Signature Version 4. For more information, see Query API Authentication.

The following is an example request that launches instances:

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2014-06-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%3host%3x-amz-date&X-Amz-Signature=525d1a96c69b5549dd78dbbec8efe264102288b83ba87b7d58d4b76b71f59fd2
Content-type: application/json
host:ec2.amazonaws.com

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-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&Version=2014-06-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%3host%3x-amz-date
&X-Amz-Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c
Content-type: application/json
host:ec2.amazonaws.com

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.

Important

Before you specify your access key ID for the AWSAccessKeyId or Credential parameter, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Endpoints

An endpoint is a URL that serves as an entry point for a web service. You can select a regional endpoint for Amazon EC2 when you make your requests to reduce latency. For more information about regions, see Region and Availability Zone Concepts. For information about the endpoints for Amazon EC2, see Regions and Endpoints in the Amazon Web Services General Reference.

If you specify the general endpoint, ec2.amazonaws.com, we use the endpoint for us-east-1. To use a different region, specify its associated endpoint. For example, if you specify ec2.us-west-2.amazonaws.com as the endpoint, we direct your request to the us-west-2 endpoint.

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 the HTTP or HTTPS protocol.

Regardless of which protocol you use, you must include a signature in every Query request. Amazon EC2 supports Signature Version 2 and Signature Version 4. For more information, see Signature Version 2 Signing Process and Signature Version 4 Signing Process in the Amazon Web Services General Reference.

Signature Version 4 requests allow you specify all the authorization parameters in a single header, for example:

Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Amz-Date: 20130813T150211Z
Host: ec2.amazonaws.com
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20130813/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=2014-06-15

In the example Query requests we present in the Amazon EC2 documentation, we omit headers and 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/2014-06-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>

To download the WSDL file for Amazon EC2, see Amazon EC2 Developer Resources.