Menu
Amazon Simple Queue Service
Developer Guide

Making Query Requests

Amazon SQS supports Query requests for calling service actions. Query requests are simple HTTP or HTTPS requests, using the GET or POST method. Query requests must contain an Action parameter to indicate the action to be performed. The response is an XML document that conforms to a schema.

Structure of a GET Request

This guide presents the Amazon SQS GET requests as URLs, which can be used directly in a browser. The URL consists of:

  • Endpoint—The resource the request is acting on (in the case of Amazon SQS, the endpoint is a queue)

  • Action—The action you want to perform on the endpoint; for example: sending a message

  • Parameters—Any request parameters

The following is an example GET request to send a message to an Amazon SQS queue.

How you structure the AUTHPARAMS depends on how you're signing your API request. For information on AUTHPARAMS in Signature Version 4, see Examples of Signed Signature Version 4 Requests.

http://sqs.us-east-2.amazonaws.com/123456789012/queue1?Action=SendMessage&MessageBody=Your%20Message%20Text​&Version=2012-11-05​&AUTHPARAMS

Important

Because the GET requests are URLs, you must URL encode the parameter values. For example, in the preceding example request, the value for the MessageBody parameter is actually Your Message Text. However, spaces are not allowed in URLs, so each space is URL encoded as "%20". The rest of the example has not been URL encoded to make it easier for you to read.

Note

Queue names and queue URLs are case-sensitive.

To make the GET examples even easier to read, this guide presents them in the following parsed format.

http://sqs.us-east-2.amazonaws.com/123456789012/queue1
?Action=SendMessage
&MessageBody=Your%20Message%20Text
&Version=2012-11-05
&Expires=2011-10-15T12:00:00Z
&AUTHPARAMS

Note

In the example Query requests we present in this guide, we use a false AWS Access Key ID and false signature, each with EXAMPLE appended. We do this to indicate that you shouldn't expect the signature in the example to be accurate based on the request parameters presented in the example. The one exception to this is in the instructions for creating Query request signatures. The example there shows a real signature based on a particular AWS Access Key ID we specify and the request parameters in the example (for more information, see Query Request Authentication).

In Amazon SQS, all parameters except MessageBody always have values that have no spaces. The value you provide for MessageBody in SendMessage requests can have spaces. In this guide, any example SendMessage Query requests with a MessageBody that includes spaces is displayed with the spaces URL encoded (as %20). For clarity, the rest of the URL isn't displayed in a URL encoded format.

The first line represents the endpoint of the request. This is the resource the request acts on. The preceding example acts on a queue, so the request's endpoint is the queue's identifier, known as the queue URL. For more details about the queue URL, see Queue Name and URL.

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, see API Actions in the Amazon SQS API Reference). For a list of the other parameters that are common to all Query requests, see Common Parameters in the Amazon SQS API Reference.

Structure of a POST Request

Amazon SQS also accepts POST requests. With a POST request, you send the query parameters as a form in the HTTP request body as described in the following procedure.

How you structure the AUTHPARAMS depends on how you're signing your API request. For information on AUTHPARAMS in Signature Version 4, see Examples of Signed Signature Version 4 Requests.

To create a POST request

  1. Assemble the query parameter names and values into a form.

    This means you put the parameters and values together like you'd for a GET request (with an ampersand separating each name-value pair). The following example shows a SendMessage request with the line breaks we use in this guide to make the information easier to read.

    Action=SendMessage
    &MessageBody=Your Message Text
    &Version=2012-11-05
    &Expires=2011-10-15T12:00:00Z
    &AUTHPARAMS
  2. Form-URL-encode the form according to the Form Submission section of the HTML specification (for more information, see http://www.w3.org/MarkUp/html-spec/html-spec_toc.html#SEC8.2.1).

    Action=SendMessage
    &MessageBody=Your+Message+Text
    &Version=2012-11-05
    &Expires=2011-10-15T12%3A00%3A00Z
    &AUTHPARAMS
  3. Add the request signature to the form (for more information, see Query Request Authentication).

    Action=SendMessage
    &MessageBody=Your+Message+Text
    &Version=2012-11-05
    &Expires=2011-10-15T12%3A00%3A00Z
    &AUTHPARAMS
  4. Provide the resulting form as the body of the POST request.

  5. Include the Content-Type HTTP header with the value set to application/x-www-form-urlencoded.

The following example shows the final POST request.

POST /queue1 HTTP/1.1
Host: sqs.us-east-2.amazonaws.com
Content-Type: application/x-www-form-urlencoded

Action=SendMessage
&MessageBody=Your+Message+Text
&Version=2012-11-05
&Expires=2011-10-15T12%3A00%3A00Z
&AUTHPARAMS

Amazon SQS requires no other HTTP headers in the request besides Content-Type. The authentication signature you provide is the same signature you'd provide if you sent a GET request (for information about the signature, see Query Request Authentication).

Note

Your HTTP client typically adds other items to the HTTP request as required by the version of HTTP the client uses. We don't include those additional items in the examples in this guide.