         | Did this page help you? Yes No Tell us about it... |
Making Query Requests
Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a Query parameter named
Action.
Endpoints
For information about this product's regions and endpoints, go to Regions and Endpoints in the Amazon Web Services General Reference.
If you just specify the general endpoint (ec2.amazonaws.com), the us-east-1 endpoint is used.
For more information about Regions, see Region and Availability Zone Concepts.
Structure of a GET Request
This guide presents the EC2 GET requests as URLs, which can be used directly in a browser. The URL consists of:
Endpoint—The web service entry point to act on (e.g., ec2.amazonaws.com, which defaults to the us-east-1 Region)
Action—The action you want to perform on the endpoint; for example: running an instance (
RunInstance)Parameters—Any request parameters
The following is an example GET request to run 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=2012-03-01&Expires=2010-10-10T12:00:00Z&Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE&SignatureVersion=2&SignatureMethod=HmacSHA256
![[Important]](http://docs.amazonwebservices.com/docs-common/images/important.png) | Important |
|---|---|
Because the GET requests are URLs, you must URL encode the parameter values. In the EC2 documentation, we leave the example GET requests unencoded to make them easier to read. |
To make the GET examples even easier to read, this guide presents them in the following parsed 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=2012-03-01 &Expires=2010-10-10T12:00:00Z &Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE &SignatureVersion=2 &SignatureMethod=HmacSHA256
The first line represents the endpoint of the request. After the endpoint is a question mark (?), which separates the endpoint from the parameters. Each parameter is separated by an ampersand (&).
The Action parameter indicates the action to perform (for a list of the
actions, go to Amazon Elastic Compute Cloud API Reference).
![[Note]](http://docs.amazonwebservices.com/docs-common/images/note.png) | Note |
|---|---|
In the example Query requests we present in the EC2 documentation, we omit the parameters
related to authentication to make it easier to focus on the ones relevant to the particular
operation. We replace them with the following literal string to remind you that a real request
includes the parameters: |
Query Parameters
Each Query request must include some common parameters to handle authentication and selection of an action. For more information, go to the Amazon Elastic Compute Cloud API Reference.
Some operations take lists of parameters. These lists are specified using the
param. notation. Values of
nn are integers starting from 1.
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. This section describes how to create the signature. The method described in the following procedure is known as signature version 2.
![[Caution]](http://docs.amazonwebservices.com/docs-common/images/caution.png) | Caution |
|---|---|
If you are currently using signature version 1: Version 1 is deprecated, and you should move to signature version 2 immediately. For information about the deprecation schedule and the differences between signature version 2 and version 1, go to Making Secure Requests to Amazon Web Services. |
To create the signature
Create the canonicalized query string that you need later in this procedure:
Sort the UTF-8 query string components by parameter name with natural byte ordering.
The parameters can come from the GET URI or from the POST body (when
Content-Typeisapplication/x-www-form-urlencoded).URL encode the parameter name and values according to the following rules:
Do not URL encode any of the unreserved characters that RFC 3986 defines.
These unreserved characters are A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and tilde ( ~ ).
Percent encode all other characters with %XY, where X and Y are hex characters 0-9 and uppercase A-F.
Percent encode extended UTF-8 characters in the form %XY%ZA....
Percent encode the space character as %20 (and not +, as common encoding schemes do).
Note Currently all AWS service parameter names use unreserved characters, so you don't need to encode them. However, you might want to include code to handle parameter names that use reserved characters, for possible future use.
Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character 61), even if the parameter value is empty.
Separate the name-value pairs with an ampersand ( & ) (ASCII code 38).
Create the string to sign according to the following pseudo-grammar (the
"\n"represents an ASCII newline).StringToSign = HTTPVerb + "\n" + ValueOfHostHeaderInLowercase + "\n" + HTTPRequestURI + "\n" + CanonicalizedQueryString <from the preceding step>The HTTPRequestURI component is the HTTP absolute path component of the URI up to, but not including, the query string. If the HTTPRequestURI is empty, use a forward slash ( / ).
Calculate an RFC 2104-compliant HMAC with the string you just created, your Secret Access Key as the key, and SHA256 or SHA1 as the hash algorithm.
For more information, go to http://www.ietf.org/rfc/rfc2104.txt.
Convert the resulting value to base64.
Use the resulting value as the value of the
Signaturerequest parameter.
| Important |
|---|---|
The final signature you send in the request must be URL encoded as specified in RFC 3986 (for more information, go to http://www.ietf.org/rfc/rfc3986.txt). If your toolkit URL encodes your final request, then it handles the required URL encoding of the signature. If your toolkit doesn't URL encode the final request, then make sure to URL encode the signature before you include it in the request. Most importantly, make sure the signature is URL encoded only once. A common mistake is to URL encode it manually during signature formation, and then again when the toolkit URL encodes the entire request. |
Example DescribeImages Request
https://ec2.amazonaws.com/ ?Action=DescribeImages &ImageId.1=ami-2bb65342 &Version=2012-03-01 &Expires=2008-02-10T12%3A00%3A00Z &SignatureVersion=2 &SignatureMethod=HmacSHA256 &AWSAccessKeyId=<Your AWS Access Key ID>
Following is the string to sign.
GET\n ec2.amazonaws.com\n /\n AWSAccessKeyId=<Your AWS Access Key ID> &Action=DescribeImages &Expires=2008-02-10T12%3A00%3A00Z &ImageId.1=ami-2bb65342 &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Version=2012-03-01
Following is the signed request.
https://ec2.amazonaws.com/ ?Action=DescribeImages &ImageId.1=ami-2bb65342 &Version=2012-03-01 &Expires=2008-02-10T12%3A00%3A00Z &Signature=<URLEncode(Base64Encode(Signature))> &SignatureVersion=2 &SignatureMethod=HmacSHA256 &AWSAccessKeyId=<Your AWS Access Key ID>
