SOAP Requests

Amazon SQS supports the SOAP message protocol for calling service actions over an HTTPS connection only. The easiest way to use the SOAP interface with your application is to use a SOAP toolkit appropriate for your programming platform. SOAP toolkits are available for most popular programming languages and platforms.

The service's Web Services Description Language (WSDL) file describes the actions along with the format and data types of the actions' requests and responses. Your SOAP toolkit interprets the WSDL file to provide your application access to the actions. For most toolkits, your application calls a service action using routines and classes provided or generated by the toolkit. For more information about the WSDL, see WSDL Location and API Version.

The API reference in this guide describes the request parameters for each action and their values. For more information, see API Reference. You might find it useful to refer to the WSDL and schema files directly to see how the parameters appear in the XML of the request generated by your toolkit, and to understand how your toolkit makes the actions available to your application code.

Structure of a SOAP Request

A SOAP request is an XML data structure that your SOAP toolkit generates and sends to the service. SQS recognizes that the request is a SOAP request by the presence of the optional SOAPAction header. If no SOAPAction header appears in the request, then the content type of the first (or only) message part must be one of the following:

text/xml
text-xml-SOAP
application/soap+xml

As described by the service WSDL, the root element of the XML structure is named after the action. You include the parameters for the request inside the root element, according to the SQS schema.

If you're using SOAP without WS-Security, you must include the authentication information in the SOAP header using the AWSAccessKeyId, Timestamp, and Signature parameters. For more information, see Request Authentication and SOAP without WS-Security.

Example SOAP Request

The following example shows the XML for a SOAP message that calls the CreateQueue action. Although you probably won't build the SOAP message for a service request manually, it is useful to see what your SOAP toolkit tries to produce when provided with the appropriate values. Many SOAP toolkits require you to build a request data structure similar to the XML to make a request.

The CreateQueue element contains the operation-specific QueueName parameter.

<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope
     xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header
     xmlns:aws="http://security.amazonaws.com/doc/2007-01-01/">
     <aws:AWSAccessKeyId>1D9FVRAYCP1VJS767E02EXAMPLE</aws:AWSAccessKeyId>
     <aws:Timestamp>2008-02-10T23:59:59Z</aws:Timestamp>
     <aws:Signature>SZf1CHmQ/nrZbsrC13hCZS061ywsEXAMPLE</aws:Signature>
  </soapenv:Header>
  <soapenv:Body>
    <CreateQueue xmlns="http://queue.amazonaws.com/doc/2008-01-01">
      <QueueName>MyQueue</QueueName>
    </CreateQueue>
  </soapenv:Body>
</soapenv:Envelope>

Specifying the Resource

Amazon SQS is a resource-based service, which means you specify the resource (the queue) you want to work with in the URI of the HTTPS request.

For example, the following SOAP request sends a message to the queue named MyQueue. Notice that the name of the queue appears in the URI of the request, and not in the SOAP message body itself (where the action and other action-specific information is specified).

POST /MyQueue HTTP/1.1
Host: queue.amazonaws.com  
<other HTTP headers here...>
      
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope
     xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header
     xmlns:aws="http://security.amazonaws.com/doc/2007-01-01/">
     <aws:AWSAccessKeyId>1D9FVRAYCP1VJS767E02EXAMPLE</aws:AWSAccessKeyId>
     <aws:Timestamp>2008-02-10T23:59:59Z</aws:Timestamp>
     <aws:Signature>SZf1CHmQ/nrZbsrC13hCZS061ywsEXAMPLE</aws:Signature>
  </soapenv:Header>
  <soapenv:Body>
    <SendMessage xmlns="http://queue.amazonaws.com/doc/2008-01-01">
      <MessageBody>This is my message</MessageBody>
    </SendMessage>
  </soapenv:Body>
</soapenv:Envelope>

SOAP Requests

Structure of a SOAP Request

Specifying the Resource

Related Topics