Migrating to Amazon SQS API Version 2009-02-01

Amazon Web Services released a new WSDL version (2009-02-01) of the Amazon Simple Queue Service (Amazon SQS) on April 4, 2009. As part of this release, we made various changes to the service. This article describes the changes in the 2009-02-01 version.


AWS Products Used: Amazon SQS
Created On: January 15, 2008


Important: This migration guide was originally released in February 2008 and written for migration to the 2008-01-01 WSDL version. In April 2009, Amazon SQS released a new WSDL version (2009-02-01). If you haven't yet migrated to the 2008-01-01 WSDL version, we recommend you migrate directly to the 2009-02-01 version. This guide has been updated for migration to the 2009-02-01 version.

Audience

This migration guide is intended for all current Amazon SQS users who are using the 2006-04-01 or 2007-05-01 WSDL versions. Any users of those WSDL versions who want to continue using Amazon SQS after November 6, 2009, must migrate to version 2008-01-01 or 2009-02-01. To ensure that you have sufficient time to adapt your applications, Amazon SQS will continue to accept requests from WSDL versions 2007-05-01 and 2006-04-01 until November 6, 2009, but only if you have sent a message to one of your queues during the period of April 6 to May 6, 2009. If you haven't sent a message to one of your queues during that period, your access to the 2006-04-01 and 2007-05-01 WSDLs will be discontinued immediately as of May 6, 2009.

Further details and timing are covered in the subsequent sections.

Why the Change?

We took an in-depth look at how our customers were using Amazon SQS and explored whether there were opportunities to further lower costs for them. We found that our customers were primarily interested in whether we could reduce the overall cost to use Amazon SQS, especially in conjunction with Amazon EC2.

There are several factors that impact the cost of Amazon SQS, including the size of the message, the amount of time the message is in the queue, and the overall number of API calls to the service. We reengineered how we administer the service internally, deprecated some Amazon SQS actions, and adjusted some built-in limits so that we could reduce the cost to operate the service.

We are passing these savings on to our customers. We have changed the pricing model so that the price follows the costs of the service. Specifically, we eliminated the per-message cost and introduced a small request-based charge.

To get the benefit of the new price, you must use WSDL version 2008-01-01 or later.

New Price for Amazon SQS

This section describes the differences between the old and new price models.

Previous Price (for previous WSDL versions)

Messages

$0.10 per 1,000 messages sent ($0.0001 per message sent)

Data Transfer

$0.10 per GB—all data transfer in

$0.18 per GB—first 10 TB / month data transfer out
$0.16 per GB—next 40 TB / month data transfer out
$0.13 per GB—data transfer out / month over 50 TB

New Price (for the 2008-01-01 WSDL version and later)

Requests

$0.01 per 10,000 Amazon SQS requests ($0.000001 per request)

Data Transfer

Data transfer rates are unchanged. However, because many customers want to use Amazon SQS in conjunction with Amazon EC2, all data transferred between Amazon EC2 and Amazon SQS is free of charge.

Tips for Reducing Your Costs

Because the previous price model was message-based and not request-based, some Amazon SQS users designed their applications to poll for new messages at a very high frequency. With the new price model, you're charged $0.000001 for each request. We therefore recommend that when you update your application to use the 2008-01-01 or 2009-02-01 version, you also evaluate your application's polling efficiency. If a large percentage of your ReceiveMessage requests return no messages, then you're probably polling too often.

To reduce the chance that you'll receive a message again that you've already processed, we recommend you promptly delete your messages after you're done processing them. Also, set the visibility timeout for the queue or message to a time sufficient to cover the processing and deletion of your messages.

Timing and Transition

New customers who sign up before May 6, 2009, can use any of the WSDL versions and will be charged according to the pricing model associated with the particular WSDL being used. After May 6, 2009, only the 2008-01-01 and 2009-02-01 versions are available to new customers.

Amazon SQS customers using the old WSDL versions have until November 6, 2009 to migrate to the 2008-01-01 or 2009-02-01 WSDL version. However, you must send a message to one of your 2006-04-01 or 2007-05-01 queues during the period of April 6 to May 6, 2009, in order to have that full migration period. If you have not sent a message to your queues during the April 6 to May 6 period, your access to the 2006-04-01 and 2007-05-01 WSDLs will be discontinued immediately on May 6, 2009.

To ensure you have sufficient time to adapt your applications, Amazon SQS will accept requests using the previous WSDL versions during the migration period. Requests using the new WSDL version will be charged according to the new pricing model, and requests using the previous WSDL versions will continue to be charged according to the previous pricing model. After November 6, 2009, Amazon SQS will only accept requests using version 2008-01-01 or 2009-02-01. At that point, your queues created with the previous WSDL versions will no longer be accessible with any WSDL version.

Queues created with the previous WSDL versions cannot be accessed with version 2008-01-01 or 2009-02-01, and queues created with version 2008-01-01 or 2009-02-01 cannot be accessed with the previous versions. During the migration period, you can use the previous WSDL versions to send requests to queues created with previous WSDL versions, and you can send requests using the new versions to queues created with the new versions.

Important: Queue names are unique for each Amazon SQS user, regardless of the WSDL version. In other words, you have a single namespace for your queues, regardless of which WSDL you use to create the queue. You must not create a queue with the 2008-01-01 or 2009-02-01 version that has the same name as a queue you created with a previous WSDL version.

However, when you request ListQueues, the WSDL version you use for the request affects which queues are included in the response. Responses to a ListQueues request using either the 2006-04-01 or 2007-05-01 WSDL include only the queues created with either of those WSDL versions, but not queues created using the 2008-01-01 or 2009-02-01 WSDL. Likewise, responses to a ListQueues request using the 2008-01-01 or 2009-02-01 WSDL include only queues created with the 2008-01-01 or 2009-02-01 WSDL version. We did this because you can't perform 2008-01-01 or 2009-02-01 operations on a queue created with a previous WSDL version (and vice versa), and it might cause problems for applications to receive names of queues they can't act upon.

Changes to the AWS Account Activity Page

Starting in February 2008, your AWS Account Activity page began displaying information about requests you sent to the previous WSDL versions and requests you sent to the new versions.

The following table lists the items that are displayed in the Amazon SQS section of the AWS Account Activity page.

Item Description New with 2008-01-01
Requests-RBP Number of requests (for the new request-based pricing in version 2008-01-01 and later)
$0.01 per 10,000 requests ($0.000001 per request)
Yes
DataTransfer-In-Bytes $0.10 per GB—all data transfer in No
DataTransfer-Out-Bytes $0.18 per GB—first 10 TB / month data transfer out No
DataTransfer-Out-Bytes $0.16 per GB—next 40 TB / month data transfer out No
DataTransfer-Out-Bytes $0.13 per GB—data transfer out / month over 50 TB No
Messages Number of messages (for the old pricing deprecated on February 6, 2008)
$0.10 per 1,000 messages sent ($0.0001 per message sent)
No

Changes to the Usage Report

In February 2008, the usage parameters that you can use choose to generate the AWS Usage Report changed. The following table lists the options you now have for Amazon SQS.

Item Description
All Usage Types Includes all usage types in the report
DataTransfer-In-Bytes All data transferred in, minus the data transferred in from Amazon EC2 instances using Amazon SQS version 2008-01-01 or later
EC2DataTransfer-In-Bytes The data transferred in from EC2 instances using Amazon SQS version 2008-01-01 or later
EC2DataTransfer-Out-Bytes All data transferred out, minus the data transferred out to Amazon EC2 instances using Amazon SQS version 2008-01-01 or later
DataTransfer-Out-Bytes-To-EC2 The data transferred out to Amazon EC2 instances using Amazon SQS version 2008-01-01 or later
Messages Messages sent using old WSDL versions
Messages-RBP Messages sent using the 2008-01-01 or 2009-02-01 version
Requests Messages sent using old WSDL versions
Requests-RBP Requests sent using the 2008-01-01 or 2009-02-01 version

Summary of Changes

The technical changes in version 2009-02-01 include the following categories:

  • New limits
  • Deprecated actions
  • Other changes

The following table lists the changes to Amazon SQS comparing the old WSDL versions with the 2009-02-01 version (note that most of the changes occurred originally in the 2008-01-01 WSDL; they're still applicable in the 2009-02-01 WSDL). Subsequent sections give more information about each change.

Change Summary Link to More Information
New Limits
Message retention time Amazon SQS now automatically deletes messages that have been in the queue for 4 days. Message Retention Time
Message size The maximum allowable message size is now 8 KB. Message Size
Number of messages received The name of the NumberOfMessages parameter (used with ReceiveMessage) has changed. Also the maximum value for this parameter has changed from 256 to 10. Number of Messages Received
Queues with no activity We reserve the right to delete a queue that has had no activity for an extended period of time. Queues with No Activity
Visibility timeout The maximum visibility timeout for a queue or message is now 12 hours. Visibility Timeout
Deprecated Actions
SetVisibilityTimeout and GetVisibilityTimeout These two actions were deprecated with the 2007-05-01 release and are now no longer available. Release notes for 2007-05-01
PeekMessage The PeekMessage action is no longer available. PeekMessage
Other Changes
Access control The access control feature (grants, permissions, etc.) has changed in its functionality. Access Control
New receipt handle When you receive a message, you now receive a receipt handle, which you use to delete the message. New Receipt Handle
New MD5 digests When you send or receive a message, Amazon SQS now returns an MD5 digest of the message body to you. New MD5 Digests
ForceDeletion with DeleteQueue When you request to delete a queue, it is now deleted regardless of whether it is empty. The ForceDeletion parameter is no longer available. Deprecation of ForceDeletion with DeleteQueue
REST API The REST API is currently not available. Unavailability of REST API
Change to format of queue URL The format of the queue URL has changed. Change to Format of Queue URL
Change to CreateQueue Amazon SQS now returns an error if you try to create a queue with the name of an existing queue while also providing a visibility timeout value different from that of the existing queue. Change to CreateQueue
Change to response structure The structure of responses has changed. Change to Response Structure
Change to attributes structure The structure of the data you provide for SetQueueAttributes and the structure of the data you receive for GetQueueAttributes has changed. Change to Attributes Structure
New attributes Queues and messages now have additional attributes that you can get. New Attributes
Change to request authentication The signature version 0 for Query requests is no longer supported, and signature version 1 is deprecated. Signature version 2 is the preferred method. All SOAP requests must now use HTTPS, and the authentication information must be in the SOAP header. Changes to Request Authentication
Change to base service name in the WSDL The base service name in the Amazon SQS WSDL has changed. Base Service Name for the WSDL

Details of the Changes

Message Retention Time

In version 2009-02-01, the message retention time is now 4 days instead of 15 days. Amazon SQS now automatically deletes any messages that have been in your queues longer than 4 days.

Message Size

In version 2009-02-01, the maximum message size is now 8 KB instead of 256 KB for both Query and SOAP requests.

If you need to send messages to the queue that are larger than 8 KB, we recommend you split the information into separate messages. Alternately, you could use Amazon Simple Storage Service or Amazon SimpleDB to hold the information and include the pointer to that information in the Amazon SQS message.

If you send a message that is larger than 8 KB to the queue, you receive a MessageTooLong error (HTTP status code 400).

Number of Messages Received

When you request ReceiveMessage, you can specify the number of messages you'd like to receive, and Amazon SQS returns that number or fewer, depending on how many are available to be received from the queue at that moment. To make it clear that the number you've specified is the maximum number of messages Amazon SQS returns, we've changed the parameter name from NumberOfMessages to MaxNumberOfMessages.

Also, we've changed the maximum value for this parameter from 256 to 10.

The following table shows a Query request for ReceiveMessage with the old API and with the 2009-02-01 version.

Old API
https://queue.amazonaws.com/A29E9VSPHGOG23/queue1
?Action=ReceiveMessage
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2007-05-01
&Expires=2007-05-12T12:00:00Z
&Signature=CN2SbNq2B2Vw1W3lbc7wpM5gzDHEXAMPLE
&NumberOfMessages=2
Version 2009-02-01
https://queue.amazonaws.com/123456789012/queue1
?Action=ReceiveMessage
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2009-02-01
&Expires=2009-02-02T12:00:00Z 
&Signature=ER34ToP9U8QRti7Ydlz9wRW6rzTEXAMPLE
&SignatureVersion=2
&SignatureMethod=HmacSHA256
&MaxNumberOfMessages=2

Queues with No Activity

We reserve the right to delete a queue without notification if one of the following actions hasn't been performed against the queue for more than 30 consecutive days: SendMessage, ReceiveMessage, DeleteMessage, GetQueueAttributes, and SetQueueAttributes.

Visibility Timeout

Each queue has a default visibility timeout of 30 seconds. You can change that value for the entire queue, and you can set the visibility timeout for messages when you receive them without affecting the queue's visibility timeout. In version 2009-02-01, the maximum visibility timeout that you can specify for a queue or message has changed from 24 hours (86400 seconds) to 12 hours (43200 seconds). You can use the ChangeMessageVisibility action to extend the message's timeout; however, the total visibility timeout for the message can't exceed 12 hours. For example, if the default visibility timeout is 1 hour, you can extend it by a maximum of 11 hours.

SetVisibilityTimeout and GetVisibilityTimeout

With the 2007-05-01 version of Amazon SQS, the SetVisibilityTimeout and GetVisibilityTimeout actions were deprecated in favor of the new SetQueueAttributes and GetQueueAttributes actions. In version 2009-02-01, SetVisibilityTimeout and GetVisibilityTimeout are no longer available.

PeekMessage

In version 2009-01-01, the PeekMessage action has been removed.

Typically, Amazon SQS users have used PeekMessage to debug small systems—specifically to confirm a message was successfully sent to the queue or deleted from the queue. To do this with version 2009-02-01, you can log the message ID and receipt handle for your messages and correlate them to confirm when a message has been received and deleted. For more information about the receipt handle, see New Receipt Handle.

Access Control

In version 2009-02-01, the access control functionality has changed. The actions AddGrant and RemoveGrant have been replaced with the new actions AddPermission and RemovePermission. The ListGrants functionality has been replaced with the GetQueueAttributes action; you can get a list of the queue's permissions by getting the queue's attributes (specifically the attribute for the access control policy for the queue). The functionality has also been expanded, so you can specifically deny someone access to a queue, or restrict access based on conditions such as the date and time, the IP address of the requester, or whether the requester is using SSL.

The permissions you can grant have changed. You can now grant only these permissions: SendMessage, ReceiveMessage, DeleteMessage, ChangeMessageVisibility, GetQueueAttributes, or * (which is the sum of all the preceding permissions). You can no longer grant someone full control permission on a queue (only you as the owner can have full control).

If you're using access control with the old APIs, there's no automatic migration of your grants to the new queues you create with the 2009-02-01 version. To manually migrate, you need to get the AWS account number for each person you want to grant permission to (the new access control system uses the AWS account number as the grantee's identifier instead of the e-mail address), and then recreate each permission on your new 2009-02-01 queues.

The new access control system also allows you to share a queue you own with anonymous users. Anonymous requests don't require an AWS Access Key ID or signature. Keep in mind that you as the queue owner are still responsible for all costs associated with requests and messages from anyone you share your queue with (be it anonymous or authenticated users).

New Receipt Handle

In previous API versions, when you sent a message to the queue, you received a message ID for that message. When you deleted the message, you had to provide the message ID. With version 2009-02-01, you still receive the message ID when you send the message to the queue. However, you also get a receipt handle when you receive that message from the queue later. This handle is a different identifier from the message ID. When you delete the message, you must provide the receipt handle instead of the message ID. Following is an example receipt handle.

MbZj6wDWli+JvwwJaBV+3dcjk2YW2vA3+STFFljTM8tJJg6HRG6PYSasuWXPJB+CwLj1FjgXUv1uSj1gUGAWV76FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ+QEauMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0=

Note: The receipt handle is associated with the act of receiving, not with the message itself. If you receive a particular message more than once, you get a different receipt handle each time you receive it. The message ID stays the same, however, and is returned each time you receive the message.

The following table shows a Query request for DeleteMessage with the old API and with the 2009-02-01 version.

Old API
https://queue.amazonaws.com/A29E9VSPHGOG23/queue1
?Action=DeleteMessage
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2007-05-01
&MessageId=17VXQHSGX0SG4ZEPPK7R%7C0QE42ST4KW7RK9HSY074%7C0Z4AN912X0H2EP8BV6XJ
&Expires=2007-05-12T12:00:00Z
&Signature=AD398uq3R02mGr1A4wj70npAaQLpEXAMPLE
Version 2009-02-01
https://queue.amazonaws.com/123456789012/queue1
?Action=DeleteMessage
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2009-02-01
&ReceiptHandle=MbZj6wDWli%2BJvwwJaBV%2B3dcjk2YW2vA3%2BSTFFljT
M8tJJg6HRG6PYSasuWXPJB%2BCwLj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGY
WbnLmpRCJVAyeMjeU5ZBdtcQ%2BQEauMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/K
SbkJ0=
&Expires=2009-02-02T12:00:00Z
&Signature=CN2SbNqB2Vw1W3lbc7wpM5gzDHEXAMPLE
&SignatureVersion=2
&SignatureMethod=HmacSHA256

A consequence of this change is that you must always receive a given message before you can delete it. With previous APIs, you could recall a message from the queue (send a message and then delete it without ever receiving it); you can no longer do this.

New MD5 Digests

In version 2009-02-01, the response for both SendMessage and ReceiveMessage includes an MD5 digest of the non-URL-encoded message body string. You can use the digests to confirm that the message was not corrupted or changed during transmission to and from the queue. For information about MD5, go to https://faqs.org/rfcs/rfc1321.html.

The following table shows the old and new response for SendMessage. For more information about the ResponseMetadata element, see Change To Response Structure.

Old API

  
  
Version 2009-02-01

   
      
      
   
   

The next table shows the old and new response for ReceiveMessage.

Old API

   
      
      
   
   
Version 2009-02-01

   
      
         
         
         
         
     
   
   

The following table gives details about the child elements of .

Name Description
MessageId No change from the old API.

Type: String

ReceiptHandle The receipt handle, which you use when later deleting the message.

Type: String

MD5OfBody The MD5 digest of the non-URL-encoded message body string.

Type: String (32 characters)

Body No change from the old API.

Type: String

Note: You can also optionally receive two attributes about the message: who sent it and when the message was put into the queue. For more information, see New Attributes.

Deprecation of ForceDeletion with DeleteQueue

With previous API versions, when you requested DeleteQueue, the queue wasn't deleted if there were messages in it (instead you got an AWS.SimpleQueueService.NonEmptyQueue error). However, you could specify the ForceDeletion parameter to override that behavior, and your queue was deleted even if there were messages in it.

In version 2009-02-01, we've changed how DeleteQueue works so that your queue is deleted regardless of whether it's empty. The ForceDeletion parameter is no longer available.

The consequence of this change is that you can no longer use DeleteQueue to determine if a queue is empty. Instead, we recommend that you use the GetQueueAttributes action to retrieve the ApproximateNumberOfMessages for the queue. Because of the distributed architecture of Amazon SQS, we do not have an exact count of the number of messages in a queue; the value we provide is our best guess. In most cases it should be close to the actual number of messages in the queue, but you should not rely on the count being precise. However, if this value remains at zero over a period of time, you can assume the queue is empty.

Unavailability of the REST API

With version 2009-02-01, the REST API is not available.

The Query API is similar to the REST API and includes all the same functionality. The following example shows a CreateQueue request with the Query API.

https://queue.amazonaws.com/
?Action=CreateQueue
&QueueName=queue2
&AWSAccessKeyId=0GS7573JW74RZM612K0AEXAMPLE
&Version=2009-02-01
&Expires=2009-02-02T12:00:00Z
&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
&SignatureVersion=2
&SignatureMethod=HmacSHA256

For comparison, here is an example REST request to create a queue.

POST /?QueueName=queue2 HTTP/1.1
Host: queue.amazonaws.com
Authorization: 0GS7573JW74RZM612K0AEXAMPLE:Esdki4ll9ogJUV3Ad6tH1QEgpMREXAMPLE
Content-Type: text/plain
AWS-Version: 2007-05-01
Date: Mon, 21 May 2007 21:12:00 GMT

Following are the main differences you should be aware of when moving from REST to Query:

  • Query uses only GET or POST. Query uses an Action parameter to indicate the action to perform. Query doesn't require the use of specific HTTP headers.
  • The authentication information normally held in the Authorization header for REST requests is split and passed in two parameters in the Query request: one for the Access Key ID and one for the signature.
  • With Query, the signature is based on a different string. For REST, the string is formed from the request headers. For Query, the string is formed from the query parameters. Instructions on how to form the string and encode it are in the Amazon Simple Queue Service Developer Guide.
  • Both Query and REST require a date in the request, but the required format is different. Query uses one of the ISO 8601 formats (e.g., 2009-04-08T21:12:00Z), whereas REST uses RFC1123 (e.g., Wed, 08 Apr 2009 21:12:00 GMT).
  • With REST, when you send or receive messages from a queue, you append /back or /front to the end of the queue URL corresponding to whether you're sending or receiving messages. With Query, this is not necessary.

Amazon SQS returns the same errors for Query that it did for REST.

Change to Format of Queue URL

In version 2009-02-01, the format of the queue URL has changed. It now contains your AWS account number. For example, if your account number is 123456789012, and you have a queue named queue1, the queue URL is https://queue.amazonaws.com/123456789012/queue1. We recommend that you always store the entire queue URL as it is returned to you by SQS when you create the queue. Don't build the queue URL from its separate components each time you need to specify the queue URL in a request; we could change the components that make up the queue URL, as we have done with the 2009-02-01 version.

Change to CreateQueue

With previous API versions, if you tried to create a queue that had the name of an existing queue, and you also provided a visibility timeout value different from that of the existing queue, you didn't get an error. The request succeeded and the queue URL of the existing queue was returned to you.

In version 2009-02-01, this same request returns the error AWS.SimpleQueueService.QueueNameExists (HTTP status code 400).

Change to Response Structure

In version 2009-02-01, the structure of the response has changed. Both successful responses and error responses have new structures.

Successful Responses

In version 2009-02-01, if the action returns action-specific data, the main response element has a child element named ActionNameResult. For example, the CreateQueue action returns a queue URL, and therefore it has a CreateQueueResult element that wraps the queue URL data in the response. See the following examples. The Amazon SQS schema shows the exact structure of the response for each action.

Also, with previous API versions, a successful response included a ResponseStatus element. In version 2009-02-01, this element has been replaced with a ResponseMetadata element, which has different contents.

Old API

   
   
Version 2009-02-01

   

The following table shows an example of a successful CreateQueue response with the old API and with the 2009-02-01 version.

Old API

    https://queue.amazonaws.com/A23E9WXPHGOG29/queue2
    
      Success
      cb919c0a-9bce-4afe-9b48-9bdf2412bb67
    
Version 2009-02-01

     
       https://queue.amazonaws.com/123456789012/queue2
     
     
        cb919c0a-9bce-4afe-9b48-9bdf2412bb67
     

Error Responses

With previous API versions, an error response had a Response element. In version 2009-02-01, this element has been replaced with an ErrorResponse element, which has different contents.

Old API

   
      
         
         
      
   
   
Version 2009-02-01

   
      
      
      
      
   
   

The following table gives details about the child elements of Error.

Name Description
Type Whether the error originated with the sender or receiver.

Type: String

Valid Values: Receiver | Sender

Code No change from the old API.

Type: String

Message No change from the old API.

Type: String

Detail Additional detail about the error. If there are no details, this might not be returned or might be empty.

Type: String

The following table shows an example error response with the old API and with the 2009-02-01 version.

Old API

   
      
         
            InvalidParameterValue
         
         
            Value (quename_nonalpha) for parameter QueueName is invalid.
            Must be an alphanumeric String of 1 to 80 in length.
         
      
   
   
      42d59b56-7407-4c4a-be0f-4c88daeea257
   
Version 2009-02-01

   
      
         Sender
      
      
         InvalidParameterValue
      
      
         Value (quename_nonalpha) for parameter QueueName is invalid.
         Must be an alphanumeric String of 1 to 80 in length.
      
      
   
   
      42d59b56-7407-4c4a-be0f-4c88daeea257
   

Change to Attributes Structure

The SetQueueAttributes action and the GetQueueAttributes action let you set and get the available attributes for queues.

With previous API versions, when you called GetQueueAttributes, you could specify the particular attribute to get using the Attribute parameter. In version 2009-02-01, this parameter's name has changed to AttributeName. The following table compares a Query request with the old API with version 2009-02-01.

Old API
https://queue.amazonaws.com/A29E9VSPHGOG23/queue2
?Action=GetQueueAttributes
&Attribute=VisibilityTimeout
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2007-05-01
&Expires=2007-05-12T12:00:00Z
&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Version 2009-02-01
https://queue.amazonaws.com/123456789012/queue2
?Action=GetQueueAttributes
&AttributeName.1=VisibilityTimeout
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2009-01-01
&Expires=2009-02-02T12:00:00Z 
&Signature=Xe4wP9f7qwTE3rGai8lxVdTiu8LEXAMPLE
&SignatureVersion=2
&SignatureMethod=HmacSHA256

Also in version 2009-02-01, the structure for attribute data has changed slightly. With the old API, you used an AttributedValue data structure to set an attribute's value, and Amazon SQS used that same structure when returning the queue's attributes in a GetQueueAttributes response. In version 2009-02-01, that data structure is called Attribute, and it has different child elements than the AttributedValue element. The following table compares the data structure in the old API with version 2009-02-01.

Old API

   
   
Version 2009-02-01

   
   

The following table compares Query requests for SetQueueAttributes with the old API and with version 2009-02-01.

Old API
https://queue.amazonaws.com/A29E9VSPHGOG23/queue2
?Action=SetQueueAttributes
&Attribute=VisibilityTimeout
&Value=35
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2007-05-01
&Expires=2007-05-12T12:00:00Z
&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Version 2009-02-01
https://queue.amazonaws.com/123456789012/queue2
?Action=SetQueueAttributes
&Attribute.Name=VisibilityTimeout
&Attribute.Value=35
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2009-02-01
&Expires=2009-02-02T12:00:00Z 
&Signature=Dddr3Sd6ljTUA9Uf6SGt8hl2UQEXAMPLE
&SignatureVersion=2
&SignatureMethod=HmacSHA256

In version 2009-02-01, the structure of the response for GetQueueAttributes has changed. Also, there are additional attributes you can get (for more information, see New Attributes).

Old API

    
      
      
    
    
      
      
    
Version 2009-02-01

    
       
          
          
       
    
    
       
    

The following table shows an example response for GetQueueAttributes with the old API and with the 2009-02-01 version.

Old API

    
      ApproximateNumberOfMessages
      2900
    
    
      VisibilityTimeout
      35
    
    
      Success
      cb919c0a-9bce-4afe-9b48-9bdf2412bb67
    
Version 2009-02-01

    
       
          ApproximateNumberOfMessages
          2900
       
       
          VisibilityTimeout
          35
       
       
          CreatedTimestamp
          1238098969
       
       
          LastModifiedTimestamp
          1238099106
       
    
     
       cb919c0a-9bce-4afe-9b48-9bdf2412bb67
    

New Attributes

As of version 2009-02-01, you can get two new attributes related to the queue's creation and modification times: CreatedTimestamp, LastModifiedTimestamp (both in UNIX milliseconds timestamp format). You can also set and get the Policy attribute, which is a JSON document listing the access control permissions on the queue.

You can also get two new attributes related to the message: SenderId (which returns the AWS account number of the person who sent the message, or the IP address if the request was anonymous), and SentTimestamp (when the message was put into the queue, in UNIX milliseconds timestamp format).

The following is an example ReceiveMessage request that gets the two attributes.

https://queue.amazonaws.com/123456789012/queue2
?Action=ReceiveMessage
&MaxNumberOfMessages=5
&VisibilityTimeout=15
&AttributeName.1=SenderId
&AttributeName.2=SentTimestamp
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2009-02-01
&Expires=2009-02-02T12:00:00Z 
&Signature=Dddr3Sd6ljTUA9Uf6SGt8hl2UQEXAMPLE
&SignatureVersion=2
&SignatureMethod=HmacSHA256

The following is an example response.


   
      
         5fea7756-0ea4-451a-a703-a558b933e274
         MbZj6wDWli+JvwwJaBV+3dcjk2YW2vA3+STFFljTM8tJJg6HRG6PYS
         Lj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ+QE
         asuWXPJB+CwauMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0=
         
         fafb00f5732ab283681e124bf8747ed1
         This is a test message
         
            SenderId
            195004372649
         
         
            SentTimestamp
            1238099229000
         
      
   
   
      b6633655-283d-45b4-aee4-4e84e0ae6afa
   

Changes to Request Authentication

Query Requests

In version 2009-02-01, signature version 0 is no longer supported for Query requests, and signature version 1 is deprecated. Signature version 2 is the recommended version. In your Query requests, you must set the parameter SignatureVersion to 2, and set the new SignatureMethod parameter to either HmacSHA1 or HmacSHA256 to indicate the particular HMAC-SHA algorithm you're using. The Amazon Simple Queue Service Developer Guide has all the details about how to form signatures using signature version 2.

SOAP Requests

You must now use HTTPS when sending all SOAP requests.

Also, you must now provide the authentication information in the SOAP header, using the namespace https://security.amazonaws.com/doc/2007-01-01/. It is no longer accepted in the SOAP body. The authentication information includes elements for AWSAccessKeyID, Timestamp, and Signature. Following is an example request showing the information in the SOAP header.





   1D9FVRAYCP1VJS767E02EXAMPLE
   2008-02-02T12:00:00Z
   SZf1CHmQnrZbsrC13hCZS061ywsEXAMPLE

...

In the 2009-02-01 WSDL, the base name of the service has changed. Specifically, QueueService has changed to QueueServiceBinding and MessageQueue has changed to MessageQueueBinding. Because the generated code from the 2009-02-01 WSDL uses these new names, you'll need to change any code you have that uses the generated code.