Prev Next

Query Requests

Query requests are simply HTTP GET requests that return XML.

A Sample Query Request

Here is an sample request that looks up traffic rank data for yahoo.com:

Example 

http://awis.amazonaws.com/?
		AWSAccessKeyId=9876543212345123
		&Timestamp=2007-01-26T01%3A15%3A38.000Z
		&Signature=oQkiPZUtQ9PlTI2l4OTRA8fjYsM%3D
		&Version=2005-07-11
		&Action=UrlInfo
		&ResponseGroup=Rank
		&Url=yahoo.com

The AWSAccessKeyID, Timestamp, SignatureVersion and Signature parameters are used to authenticate and authorize your request. The Timestamp and Signature values must be generated anew for each request.

The Action, ResponseGroup, and Url parameters control what information is returned.

Authenticating Query Requests

AWS uses request authentication to verify that a request came from a registered developer and then identify the account for billing.

Upon creation an AWS account is assigned an Access Key ID and a Secret Access Key. The Access Key ID is passed into a request in the AWSAccessKeyId parameter to identify the account responsible for the request. To protect from impersonation, the request sender also signs the request using a hash calculated using the Secret Access Key. This hash is passed into the Signature parameter. The Secret Access Key should never be shared with anyone.

The following parameters are required to authenticate each request:

ParameterDescription
AWSAccessKeyId Your AWS Access Key Id
TimestampThe current time in UTC format. Authorization fails if the time stamp differs by more than 15 minutes from the clock on the Amazon servers. The Timestamp must be URL encoded.
Signature A request signature calculated by concatenating the Action name and Timestamp then calculating an RFC 2104-compliant HMAC-SHA1 hash of that string using the Secret Access Key as the key as described below.

Note:

The best way to learn how to sign requests is to see the code samples in the Resource Center for examples using Java, C#, PHP, Perl and Ruby.

If there is no code sample in your language of choice, the following steps describe how to calculate the Timestamp and Signature:

  1. Calculate the Timestamp value in UTC time with format: yyyy-MM-ddTHH:mm:ss.fffZ. For more information see: http://www.w3.org/TR/xmlschema-2/#dateTime
  2. Concatenate the Action name and the Timestamp value.
  3. Create an RFC 2104 compliant HMAC-SHA1 hash on the Action+Timestamp string, using the Secret Access Key as the "key". For more information see: http://www.ietf.org/rfc/rfc2104.txt.
  4. Base64 encode the hash to get the signature.
  5. URL encode the signature. Note: The resulting signature cannot contain any "+"'s. So, for example in C# you must use HttpUtility.UrlPathEncode instead of HttpUtility.UrlEncode. You can find reference charts for URL encoding at i-Technica and W3 Schools.
  6. Pass the computed signature in the Signature parameter of your request.
  7. URL encode the Timestamp value and pass it in the with your request.

If your request cannot be authenticated, you will get an error message explaining the reason.

		<Response>
			<Errors>
				<Error>
					<Code>AuthFailure</Code>
					<Message>AWS was not able to validate the provided access credentials</Message>
				</Error>
			</Errors>
			<RequestID>6bbc7909-375e-4bd6-a37f-692ce855c3c0</RequestID>
		</Response>

If you get an Authentication failure then one of the following is probably true:

Prev Copyright Information Next