Upload
others
View
2
Download
0
Embed Size (px)
Citation preview
Amazon Simple Queue ServiceAPI Reference
API Version 2009-02-01
Amazon Simple Queue Service: API ReferenceCopyright © 2011 Amazon Web Services LLC or its affiliates. All rights reserved.
Amazon Simple Queue Service API Reference
Table of ContentsWelcome ............................................................................................................................................................. 1API Reference .................................................................................................................................................... 3
WSDL Location and API Version ............................................................................................................ 3Common Query Parameters ................................................................................................................... 5Common Errors ...................................................................................................................................... 5API Actions ............................................................................................................................................. 9
AddPermission ............................................................................................................................ 10ChangeMessageVisibility ............................................................................................................ 12CreateQueue ............................................................................................................................... 14DeleteMessage ........................................................................................................................... 17DeleteQueue ............................................................................................................................... 19GetQueueAttributes ..................................................................................................................... 21ListQueues .................................................................................................................................. 25ReceiveMessage ......................................................................................................................... 27RemovePermission ..................................................................................................................... 31SendMessage ............................................................................................................................. 33SetQueueAttributes ..................................................................................................................... 35
Glossary ........................................................................................................................................................... 38Document History ............................................................................................................................................. 40Index ................................................................................................................................................................. 41
Amazon Simple Queue Service API Reference
Welcome
Topics
• Audience (p. 1)
• Amazon SQS Resources (p. 2)
This is the Amazon Simple Queue Service API Reference. This section describes who should read thisguide, how the guide is organized, and other resources related to the Amazon Simple Queue Service(Amazon SQS).
The Amazon Simple Queue Service will occasionally be referred to within this guide as simply "SQS"; allcopyrights and legal protections still apply.
Use the following links to get started using the Amazon SQS API Reference:
• API Actions (p. 9): An alphabetical list of all Amazon SQS actions.
• Common Query Parameters (p. 5): Parameters that all Query actions can use.
• Common Errors (p. 5): Client and server errors that all actions can return.
• Regions and Endpoints: Regions and endpoints available for Amazon SQS.
• WSDL Location and API Version (p. 3): WSDL locations for each region.
AudienceThis guide is intended for developers who are building distributed web-enabled applications. An applicationcould typically use Amazon SQS to move data between distributed application components performingdifferent tasks, without losing messages or requiring each component to be always available.
To use SQS, you must have an AWS account and be signed up to use SQS. For more information, goto the Amazon Simple Queue Service Getting Started Guide .
Required Knowledge and SkillsUse of this guide assumes you are familiar with the following:
• XML (for an overview, go to W3 Schools XML Tutorial )
• Basic understanding of web services (for an overview, go to W3 Schools Web Services Tutorial )
API Version 2009-02-011
Amazon Simple Queue Service API ReferenceAudience
• A programming language for consuming a web service and any related tools
You should also have read the Amazon Simple Queue Service Getting Started Guide, which includes atutorial showing you how to perform basic functions with a queue.
Amazon SQS ResourcesThe following table lists related resources that you'll find useful as you work with this service.
DescriptionResource
The getting started guide provides a quick tutorial of theservice based on a simple use case. Examples andinstructions in multiple programming languages are included.
Amazon Simple Queue Service GettingStarted Guide
The developer guide provides a detailed discussion of theservice. It includes an architectural overview and aprogramming reference
Amazon Simple Queue ServiceDeveloper Guide
The release notes give a high-level overview of the currentrelease.They specifically note any new features, corrections,and known issues.
Amazon SQS Release Notes
A central starting point to find documentation, code samples,release notes, and other information to help you buildinnovative applications with AWS.
AWS Developer Resource Center
A community-based forum for developers to discuss technicalquestions related to Amazon SQS.
Discussion Forums
The home page for AWS Technical Support, including accessto our Developer Forums, Technical FAQs, Service Statuspage, and AWS Premium Support (if you are subscribed tothis program).
AWS Support Center
The primary web page for information about AWS PremiumSupport, a one-on-one, fast-response support channel to helpyou build and run applications on AWS Infrastructure Services.
AWS Premium Support Information
The primary web page for information about Amazon SQS.Product information for Amazon SQS
A central contact point for inquiries concerning AWS billing,account, events, abuse etc.
Contact Us
Detailed information about the copyright and trademark usageat Amazon.com and other topics.
Conditions of Use
API Version 2009-02-012
Amazon Simple Queue Service API ReferenceAmazon SQS Resources
API Reference
Topics
• WSDL Location and API Version (p. 3)
• Common Query Parameters (p. 5)
• Common Errors (p. 5)
• API Actions (p. 9)
This section contains the API reference for Amazon SQS.
Note
AWS provides libraries, sample code, tutorials, and other resources for software developers whoprefer to build applications using language-specific APIs instead of Amazon SQS's Query API.These libraries provide basic functions (not included in the Query API), such as requestauthentication, request retries, and error handling so you can get started more easily. Librariesand resources are available for the following languages:
• Java
• PHP
• Ruby
• Windows and .NET
For libraries and sample code in all languages, go to Sample Code & Libraries.
WSDL Location and API VersionThe Amazon SQS API is published through a Web Services Description Language (WSDL). The versionof the Amazon SQS API supported with this document is 2009-02-01.
The SQS WSDL is available by locale at the following endpoints:
URLRegion
http://sqs.us-east-1.amazonaws.com/doc/2009-02-01/QueueService.wsdlUS East (NorthernVirginia) Region
API Version 2009-02-013
Amazon Simple Queue Service API ReferenceWSDL Location and API Version
URLRegion
http://sqs.us-west-1.amazonaws.com/doc/2009-02-01/QueueService.wsdlUS West (NorthernCalifornia) Region
http://sqs.eu-west-1.amazonaws.com/doc/2009-02-01/QueueService.wsdlEU (Ireland) Region
http://sqs.ap-southeast-1.amazonaws.com/doc/2009-02-01/QueueService.wsdlAsia Pacific (Singapore)Region
http://sqs.ap-northeast-1.amazonaws.com/doc/2009-02-01/QueueService.wsdlAsia Pacific (Tokyo)Region
Note
As of 2009 the SQS schema is incorporated into the WSDL. There is no longer a separate URLfor the schema.
API VersionsThe version of an API is specified as a date, such as 2009-02-01. When a new version of the API isreleased, previous versions are supported for a limited time to allow applications to continue to functionuntil they are upgraded. If you're new to Amazon SQS, you must use version 2009-02-01. If you try touse a previous version, you'll receive the NotAuthorizedToUseVersion error.
Important
The 2009-02-01 version is compatible with 2008-01-01 but not with any other previous APIversions. Queues created with previous versions are not accessible with the 2008-01-01 or aboveversion, and queues created with the 2008-01-01and above version are not accessible withprevious versions. If you currently use a previous version, you must upgrade to at least the2008-01-01 version if you want to continue using SQS. For information about what's different inthe new version, go to the Amazon SQS Migration Guide for Version 2008-01-01.
The version of the API can be found in the URLs of the WSDL file. It can also be found in the targetnamespace of the WSDL file.
You can retrieve the WSDL for a previous version of the API by replacing the version date in the URLwith the desired version. For example, the following retrieves the WSDL for API version 2007-05-01.
http://sqs.us-east-1.amazonaws.com/doc/2007-05-01/QueueService.wsdl
Specifying the API VersionFor all requests, you must explicitly request the API version you want to use. Specifying the versionensures that the service does not return response elements that your application is not designed to handle.
In Query requests, you include the Version parameter.
http://sqs.us-east-1.amazonaws.com/?Action=CreateQueue&QueueName=queue2&AWSAccessKeyId=0GS7573JW74RZM612K0AEXAMPLE&Version=2009-02-01
API Version 2009-02-014
Amazon Simple Queue Service API ReferenceAPI Versions
&Expires=2008-02-10T12:00:00Z&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE&SignatureVersion=2&SignatureMethod=HmacSHA256
Common Query ParametersThe following table lists common parameters used by Query requests to SQS.
DescriptionParameter Name
The action to perform. For example: CreateQueue..Action
Your Access Key ID. For example: 0AS7253JW73RRM652K02. Formore information, see Your AWS Identifiers in the Amazon SQSDeveloper Guide.
AWSAccessKeyId
The date and time at which the signature included in the requestexpires, in the format YYYY-MM-DDThh:mm:ssZ, as specified in theISO 8601 standard. Query requests must include either Timestampor Expires, but not both.
Expires
A request signature (for information, see Request Authentication inthe Amazon SQS Developer Guide). For example:Qnpl4Qk/7tINHzfXCiT7VbBatDA=.
Signature
Required when you use signature version 2 with Query requests. Formore information, see Query Request Authentication in the AmazonSQS Developer Guide.
SignatureMethod
For more information, see Query Request Authentication in theAmazon SQS Developer Guide.
SignatureVersion
The date and time the request is signed, in the formatYYYY-MM-DDThh:mm:ssZ, as specified in the ISO 8601 standard.Query requests must include either Timestamp or Expires, but notboth.
Timestamp
The API version to use, as specified in the WSDL. For example:2009-02-01.
Version
For Query requests, parameter values must be URL-encoded. This is true for any Query parameterpassed to SQS and is typically necessary in the Signature, ReceiptHandle, and MessageBodyparameters. Some clients do this automatically, but this is not the norm.
Common ErrorsTopics
• List of Errors (p. 6)
• Example Response for AuthFailure Error (p. 8)
API Version 2009-02-015
Amazon Simple Queue Service API ReferenceCommon Query Parameters
This section lists the errors shared by all actions. Errors specific to an action are listed in the topic aboutthat action. For information about the structure of an error response, see Responses section in the AmazonSQS Developer Guide.
Important
We might throttle requests to Amazon SQS as necessary. When we throttle, we return a 503(service unavailable) HTTP status code.Your system should be prepared to retry any requestthat receives a 503 code.
List of Errors
HTTPStatusCode
DescriptionError
403Access to the resource is denied.AccessDenied
401A value used for authentication could notbe validated, such as Signature. Foran example, see Example Response forAuthFailure Error (p. 8).
AuthFailure
500There is an internal problem with SQS,which you cannot resolve. Retry therequest. If the problem persists, contactus through the Amazon SQS DiscussionForums.
AWS.SimpleQueueService.InternalError
400Queue does not exist.AWS.SimpleQueueService.NonExistentQueue
400The query parameter <parameter> isinvalid. Its structure conflicts with that ofanother parameter.
ConflictingQueryParameter
500There is an internal problem with SQS,which you cannot resolve. Retry therequest. If the problem persists, contactus through the Amazon SQS DiscussionForums.
InternalError
401AWS was not able to validate theprovided access credentials.
InvalidAccessKeyId
400The action specified was invalid.InvalidAction
404The address <address> is not valid forthis web service.
InvalidAddress
400Invalid HTTP request. Reason:<reason>.
InvalidHttpRequest
400Two parameters were specified thatcannot be used together, such asTimestamp and Expires.
InvalidParameterCombination
API Version 2009-02-016
Amazon Simple Queue Service API ReferenceList of Errors
HTTPStatusCode
DescriptionError
400One or more parameters cannot bevalidated.
InvalidParameterValue
400The query parameter <parameter> isinvalid. Please see service documentationfor correct syntax.
InvalidQueryParameter
400The service cannot handle the request.Request is invalid.
InvalidRequest
403The provided security credentials are notvalid. Reason: <reason>.
InvalidSecurity
400The security token used in the request isinvalid. Reason: <reason>.
InvalidSecurityToken
400Version not well formed: <version>.Must be in YYYY-MM-DD format.
MalformedVersion
403Request must contain AWSAccessKeyIdor X.509 certificate.
MissingClientTokenId
401AWS was not able to authenticate therequest: access credentials are missing.
MissingCredentials
400A required parameter is missing.MissingParameter
400An incorrect version was specified in therequest.
NoSuchVersion
401Users who sign up to use Amazon SQSafter February 1, 2008, must use APIversion 2008-01-01 and above; notprevious API versions.
NotAuthorizedToUseVersion
400The timestamp used with the signaturehas expired.
RequestExpired
503Request is throttled.RequestThrottled
503A required server needed by SQS isunavailable.This error is often temporary;resend the request after a short wait.
ServiceUnavailable
400Signed info is corrupt.WSSecurityCorruptSignedInfo
400Timestamp for created date must be inISO8601 format.
WSSecurityCreatedDateIncorrectFormat
400BinarySecurityToken must haveEncodingType of <type>.
WSSecurityEncodingTypeError
400Timestamp for expires date must be inISO8601 format.
WSSecurityExpiresDateIncorrectFormat
API Version 2009-02-017
Amazon Simple Queue Service API ReferenceList of Errors
HTTPStatusCode
DescriptionError
400BinarySecurityToken has bad ValueType.WSSecurityIncorrectValuetype
400BinarySecurityToken must have attributeValueType.
WSSecurityMissingValuetype
400Request must not contain more than oneBinarySecurityToken with valueType<type>.
WSSecurityMultipleCredentialError
400Request must not contain more than oneBinarySecurityToken with valueType<type> or <type>.
WSSecurityMultipleX509Error
400Error while processing signature element.WSSecuritySignatureError
400SignatureValue is missing or empty.WSSecuritySignatureMissing
400Request has no SignedInfo.WSSecuritySignedInfoMissing
400Request has expired.WSSecurityTimestampExpired
400Timestamp must have Expires element.WSSecurityTimestampExpiresMissing
400Security Header Element is missing thetimestamp element.
WSSecurityTimestampMissing
400Request cannot contain both Credentialand an X.509 certificate.
WSSecurityX509CertCredentialError
400Could not parse X.509 certificate.X509ParseError
Example Response for AuthFailure ErrorThe following sample response is for an AuthFailure error.
<ErrorResponse> <Error> <Type> Sender </Type> <Code> AuthFailure </Code> <Message> The provided signature is not valid for this access token </Message> <Detail/> </Error> <RequestId> ef3aba6a-dc84-4937-91bf-cef2ddd6775a
API Version 2009-02-018
Amazon Simple Queue Service API ReferenceExample Response for AuthFailure Error
</RequestId></ErrorResponse>
API ActionsThe Query and SOAP APIs implement the following actions:
Actions for Queues
• CreateQueue (p. 14)
• DeleteQueue (p. 19)
• ListQueues (p. 25)
• GetQueueAttributes (p. 21)
• SetQueueAttributes (p. 35)
Actions for Access Control on Queues
• AddPermission (p. 10)
• RemovePermission (p. 31)
Actions for Messages
• SendMessage (p. 33)
• ReceiveMessage (p. 27)
• DeleteMessage (p. 17)
• ChangeMessageVisibility (p. 12)
Note to Users of Previous Versions
With the release of version 2009-02-01 we changed how you reference a queue. In previousWSDL versions you used the following structure:
http://sqs.us-east-1.amazonaws.com/<queuename>
In the 2009-02-01 WSDL, you must insert the queue owner's AWS account number before thequeue name in all MessageQueue service requests (that is, all actions other thanCreateQueue (p. 14) and ListQueues (p. 25)):
http://sqs.us-east-1.amazonaws.com/<acct#>/<queuename>
API Version 2009-02-019
Amazon Simple Queue Service API ReferenceAPI Actions
AddPermission
DescriptionThe AddPermission action adds a permission to a queue for a specific principal.This allows for sharingaccess to the queue.
When you create a queue, you have full control access rights for the queue. Only you (as owner of thequeue) can grant or deny permissions to the queue. For more information about these permissions, seeShared Queues in the Amazon SQS Developer Guide.
Note
AddPermission writes an SQS-generated policy. If you want to write your own policy, useSetQueueAttributes (p. 35) to upload your policy. For more information about writing your ownpolicy, see Appendix: The Access Policy Language in the Amazon SQS Developer Guide.
Request ParametersThe following table lists the special request parameters the AddPermission action uses in addition tothe common parameters all actions use (for more information, see Common Query Parameters (p. 5)).
Note
Some API operations take lists of parameters. These lists are specified using the param.nnotation.Values of n are integers starting from 1. For example, a parameter list with two elementslooks like this:
&Attribute.1=this&Attribute.2=that
RequiredDescriptionName
YesThe unique identification of the permission you'resetting.
Type: String (example: AliceSendMessage)
Constraints: Maximum 80 characters; alphanumericcharacters, hyphens (-), and underscores (_) areallowed.
Default: None
Label
YesThe AWS account number of the principal who will begiven permission. The principal must have an AWSaccount, but does not need to be signed up forAmazon SQS. For information about locating the AWSaccount identification, see Your AWS Identifiers in theAmazon SQS Developer Guide.
Type: String
Constraints: Valid 12-digit AWS account number,without hyphens
Default: None
AWSAccountId.n
API Version 2009-02-0110
Amazon Simple Queue Service API ReferenceAddPermission
RequiredDescriptionName
YesThe action you want to allow for the specified principal.For more information about these actions, seeUnderstanding Permissions in the Amazon SQSDeveloper Guide.
Type: String
Valid values: * | SendMessage |ReceiveMessage | DeleteMessage |ChangeMessageVisibility |GetQueueAttributes
Default: None
ActionName.n
Response ElementsThe AddPermission response only returns metadata. For more information, see Responses in theAmazon SQS Developer Guide.
ExamplesThe following example Query request grants a SendMessage permission to the principal whose AWSaccount number is 125074342641.
Sample Request
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=AddPermission&Label=testLabel&AWSAccountId.1=125074342641&ActionName.1=SendMessage&AWSAccountId.2=125074342642&ActionName.2=ReceiveMessage&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<AddPermissionResponse> <ResponseMetadata> <RequestId> 9a285199-c8d6-47c2-bdb2-314cb47d599d </RequestId> </ResponseMetadata></AddPermissionResponse>
Related Actions• RemovePermission (p. 31)
API Version 2009-02-0111
Amazon Simple Queue Service API ReferenceAddPermission
ChangeMessageVisibility
DescriptionThe ChangeMessageVisibility action changes the visibility timeout of a specified message in a queueto a new value. The maximum allowed timeout value you can set the value to is 12 hours. This meansyou can't extend the timeout of a message in an existing queue to more than a total visibility timeout of12 hours. (For more information visibility timeout, see Visibility Timeout in the Amazon SQS DeveloperGuide.)
For example, let's say the timeout for the queue is 30 seconds, and you receive a message. Once you're20 seconds into the timeout for that message (i.e., you have 10 seconds left), you extend it by 60 secondsby calling ChangeMessageVisibility with VisibilityTimeoutset to 60 seconds.You have thenchanged the remaining visibility timeout from 10 seconds to 60 seconds.
Important
If you attempt to set the VisibilityTimeout to an amount more than the maximum time left,Amazon SQS returns an error. It will not automatically recalculate and increase the timeout tothe maximum time remaining.
Important
Unlike with a queue, when you change the visibility timeout for a specific message, that timeoutvalue is applied immediately but is not saved in memory for that message. If you don’t delete amessage after it is received, the visibility timeout for the message the next time it is receivedreverts to the original timeout value, not the value you set with the ChangeMessageVisibilityaction.
Request ParametersThe following table lists the special request parameters the action uses (in addition to the common requestparameters listed in Common Query Parameters (p. 5)).
RequiredDescriptionName
YesThe receipt handle associated with the message whosevisibility timeout you want to change. This parameter isreturned by the ReceiveMessage (p. 27) action.
Type: String
Default: None
ReceiptHandle
YesThe new value for the message's visibility timeout (inseconds).
Type: Integer from 0 to 43200 (maximum 12 hours)
Constraints: This value is limited to 43200 seconds (12hours)
Default: None
VisibilityTimeout
API Version 2009-02-0112
Amazon Simple Queue Service API ReferenceChangeMessageVisibility
Response ElementsThe response contains no special elements besides the common elements listed in the Responses sectionin the Amazon SQS Developer Guide.
Special ErrorsThe action returns no errors besides the common errors listed in Common Errors (p. 5).
ExamplesThe following example Query request changes the visibility timeout for a message to 60 seconds.
Sample Request
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=ChangeMessageVisibility&VisibilityTimeout=60&ReceiptHandle=MbZj6wDWli%2BJvwwJaBV%2B3dcjk2YW2vA3%2BSTFFljTM8tJJg6HRG6PYSasuWXPJB%2BCwLj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ%2BQEauMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0=&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<ChangeMessageVisibilityResponse> <ResponseMetadata> <RequestId> 6a7a282a-d013-4a59-aba9-335b0fa48bed </RequestId> </ResponseMetadata></ChangeMessageVisibilityResponse>
Related Actions• DeleteMessage (p. 17)
• ReceiveMessage (p. 27)
API Version 2009-02-0113
Amazon Simple Queue Service API ReferenceChangeMessageVisibility
CreateQueue
DescriptionThe CreateQueue action creates a new queue.
When you request CreateQueue, you provide a name for the queue.To successfully create a new queue,you must provide a name that is unique within the scope of your own queues. If you provide the name ofan existing queue, a new queue isn't created and an error isn't returned. Instead, the request succeedsand the queue URL for the existing queue is returned (for more information about queue URLs, see Queueand Message Identifiers in the Amazon SQS Developer Guide). Exception: if you provide a value forDefaultVisibilityTimeout that is different from the value for the existing queue, you receive anerror.
Note
If you delete a queue, you must wait at least 60 seconds before creating a queue with the samename.
A default value for the queue's visibility timeout (30 seconds) is set when the queue is created.You canoverride this value with the DefaultVisibilityTimeout request parameter. For more information,see Visibility Timeout in the Amazon SQS Developer Guide.
Request ParametersThe following table lists the special request parameters the CreateQueue action uses in addition to thecommon parameters all actions use (for more information, see Common Query Parameters (p. 5)).
RequiredDescriptionName
YesThe name to use for the queue created.
Type: String
Constraints: Maximum 80 characters; alphanumericcharacters, hyphens (-), and underscores (_) areallowed.
QueueName
NoThe visibility timeout (in seconds) to use for this queue.
Type: Integer
Constraints: 0 to 43200 (maximum 12 hours)
Default: 30 seconds
DefaultVisibilityTimeout
Response ElementsThe following table lists the elements the CreateQueue response includes in addition to the elementsreturned in all successful responses (for more information, see Responses section in the Amazon SQSDeveloper Guide.
DescriptionName
The queue URL for the queue you created.
Type: String
Ancestor: CreateQueueResult
QueueUrl
API Version 2009-02-0114
Amazon Simple Queue Service API ReferenceCreateQueue
Special ErrorsThe following table lists the special errors the CreateQueue action returns in addition to the commonerrors all actions return (for more information, see Common Errors (p. 5)).
HTTPStatusCode
DescriptionError
400You must wait 60 seconds afterdeleting a queue before you cancreate another with the samename.
AWS.SimpleQueueService.QueueDeletedRecently
400Queue already exists. SQSreturns this error only if therequest includes aDefaultVisibilityTimeoutvalue that differs from the valuefor the existing queue.
AWS.SimpleQueueService.QueueNameExists
ExamplesThe following example Query request creates a new queue named queue2.
Sample Request
http://sqs.us-east-1.amazonaws.com/?Action=CreateQueue&DefaultVisibilityTimeout=40&QueueName=testQueue&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<CreateQueueResponse> <CreateQueueResult> <QueueUrl> http://sqs.us-east-1.amazonaws.com/123456789012/testQueue </QueueUrl> </CreateQueueResult> <ResponseMetadata> <RequestId> 7a62c49f-347e-4fc4-9331-6e8e7a96aa73 </RequestId> </ResponseMetadata></CreateQueueResponse>
API Version 2009-02-0115
Amazon Simple Queue Service API ReferenceCreateQueue
Related Actions• DeleteQueue (p. 19)
• ListQueues (p. 25)
• SetQueueAttributes (p. 35)
API Version 2009-02-0116
Amazon Simple Queue Service API ReferenceCreateQueue
DeleteMessage
DescriptionThe DeleteMessage action deletes the specified message from the specified queue.You specify themessage by using the message's receipt handle and not the message ID you received when you sentthe message. Even if the message is locked by another reader due to the visibility timeout setting, it isstill deleted from the queue. If you leave a message in the queue for more than 4 days, SQS automaticallydeletes it.
Note
The receipt handle is associated with a specific instance of receiving the message. If you receivea message more than once, the receipt handle you get each time you receive the message isdifferent. When you request DeleteMessage, if you don't provide the most recently receivedreceipt handle for the message, the request will still succeed, but the message might not bedeleted.
Important
It is possible you will receive a message even after you have deleted it. This might happen onrare occasions if one of the servers storing a copy of the message is unavailable when yourequest to delete the message. The copy remains on the server and might be returned to youagain on a subsequent receive request.You should create your system to be idempotent so thatreceiving a particular message more than once is not a problem.
Request ParametersThe following table lists the special request parameters the DeleteMessage action uses in addition tothe common parameters all actions use (for more information, see Common Query Parameters (p. 5)).
RequiredDescriptionName
YesThe receipt handle associated with the message you want todelete.
Type: String
ReceiptHandle
Response ElementsThe response contains no special elements besides the common elements returned in all successfulresponses (for more information, see Responses section in the Amazon SQS Developer Guide.
Special ErrorsThe request doesn't fail unless the ReceiptHandle is malformed. Even if the specified ReceiptHandledoesn't exist or isn't the most recently returned receipt handle for that message, the action returns Success.
ExamplesThe following example Query request deletes a message from the specified queue.
API Version 2009-02-0117
Amazon Simple Queue Service API ReferenceDeleteMessage
Sample Request
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=DeleteMessage&ReceiptHandle=MbZj6wDWli%2BJvwwJaBV%2B3dcjk2YW2vA3%2BSTFFljTM8tJJg6HRG6PYSasuWXPJB%2BCwLj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ%2BQEauMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0=&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<DeleteMessageResponse> <ResponseMetadata> <RequestId> b5293cb5-d306-4a17-9048-b263635abe42 </RequestId> </ResponseMetadata></DeleteMessageResponse>
Related Actions• ReceiveMessage (p. 27)
• SendMessage (p. 33)
API Version 2009-02-0118
Amazon Simple Queue Service API ReferenceDeleteMessage
DeleteQueue
DescriptionThe DeleteQueue action deletes the queue specified by the queue URL, regardless of whether thequeue is empty. If the specified queue does not exist, SQS returns a successful response.
Caution
Use DeleteQueue with care; once you delete your queue, any messages in the queue are nolonger available.
When you delete a queue, the deletion process takes up to 60 seconds. Requests you send involvingthat queue during the 60 seconds might succeed. For example, a SendMessage request might succeed,but after the 60 seconds, the queue and that message you sent no longer exist. Also, when you deletea queue, you must wait at least 60 seconds before creating a queue with the same name.
We reserve the right to delete queues that have had no activity for more than 30 days. For more information,see About SQS Queues in the Amazon SQS Developer Guide.
Request ParametersThe DeleteQueue action uses no special request parameters besides the common request parametersall actions use (for more information, see About SQS Queues in the Amazon SQS Developer Guide).
Response ElementsThe response contains no special elements besides the common elements in all successful responses(for more information, see Responses section in the Amazon SQS Developer Guide.
Special ErrorsThe DeleteQueue action returns no special errors besides the common errors all actions return (formore information, see Common Errors (p. 5)).
ExamplesThe following example Query request deletes the specified queue.
Sample Request
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=DeleteQueue&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
API Version 2009-02-0119
Amazon Simple Queue Service API ReferenceDeleteQueue
Sample Response
<DeleteQueueResponse> <ResponseMetadata> <RequestId> 6fde8d1e-52cd-4581-8cd9-c512f4c64223 </RequestId> </ResponseMetadata></DeleteQueueResponse>
Related Actions• CreateQueue (p. 14)
• ListQueues (p. 25)
API Version 2009-02-0120
Amazon Simple Queue Service API ReferenceDeleteQueue
GetQueueAttributes
DescriptionThe GetQueueAttributes action returns one or all attributes of a queue.
Note
Some API operations take lists of parameters. These lists are specified using the param.nnotation.Values of n are integers starting from 1. For example, a parameter list with two elementslooks like this:
&Attribute.1=this&Attribute.2=that
Request ParametersThe following table lists the special request parameters the GetQueueAttributes action uses in additionto the common request parameters all actions use (for more information, see Common QueryParameters (p. 5)).
API Version 2009-02-0121
Amazon Simple Queue Service API ReferenceGetQueueAttributes
RequiredDescriptionName
YesThe attribute you want to get.
• All—returns all values.
• ApproximateNumberOfMessages—returns the approximatenumber of visible messages in a queue. For more information,see Resources Required to Process Messages in the AmazonSQS Developer Guide.
• ApproximateNumberOfMessagesNotVisible—returns theapproximate number of messages that are not timed-out andnot deleted. For more information, see Resources Requiredto Process Messages in the Amazon SQS Developer Guide.
• VisibilityTimeout—returns the visibility timeout for the queue.For more information about visibility timeout, see VisibilityTimeout in the Amazon SQS Developer Guide.
• CreatedTimestamp—returns the time when the queue wascreated (epoch time in seconds).
• LastModifiedTimestamp—returns the time when the queuewas last changed (epoch time in seconds).
• Policy—returns the queue's policy.
• MaximumMessageSize—returns the limit of how many bytesa message can contain before Amazon SQS rejects it.
• MessageRetentionPeriod—returns the number of secondsAmazon SQS retains a message.
• QueueArn—returns the queue's Amazon resource name(ARN).
Type: String
Valid values: All | ApproximateNumberOfMessages |ApproximateNumberOfMessagesNotVisible |VisibilityTimeout | CreatedTimestamp |LastModifiedTimestamp | Policy |MaximumMessageSize | MessageRetentionPeriod |QueueArn
Default: None
AttributeName.n
Response ElementsThe following table lists the response elements the GetQueueAttributes action returns in addition tothe common response elements all actions return (for more information, see Responses section in theAmazon SQS Developer Guide.
API Version 2009-02-0122
Amazon Simple Queue Service API ReferenceGetQueueAttributes
DescriptionName
An element containing each attribute's information.
Ancestor: GetQueueAttributesResult
Children:
• Name—The attribute name you requested.
• Value—The value for the requested attribute. The CreatedTimestampand the LastModifiedTimestamp are each returned as an integerrepresenting the epoch time in seconds.
Attribute
Special ErrorsThe following table lists the special errors the GetQueueAttributes action returns in addition to thecommon errors all actions return (for more information, see Common Errors (p. 5)).
HTTP StatusCode
DescriptionError
400Unknown attributeInvalidAttributeName
ExamplesThe following example Query request gets all the attribute values for the specified queue.
Sample Request
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=GetQueueAttributes&AttributeName=All&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<GetQueueAttributesResponse> <GetQueueAttributesResult> <Attribute> <Name>VisibilityTimeout</Name> <Value>30</Value> </Attribute> <Attribute> <Name>ApproximateNumberOfMessages</Name> <Value>0</Value> </Attribute> <Attribute>
API Version 2009-02-0123
Amazon Simple Queue Service API ReferenceGetQueueAttributes
<Name>ApproximateNumberOfMessagesNotVisible</Name> <Value>0</Value> </Attribute> <Attribute> <Name>CreatedTimestamp</Name> <Value>1286771522</Value> </Attribute> <Attribute> <Name>LastModifiedTimestamp</Name> <Value>1286771522</Value> </Attribute> <Attribute> <Name>QueueArn</Name> <Value>arn:aws:sqs:us-east-1:123456789012:qfoo</Value> </Attribute> <Attribute> <Name>MaximumMessageSize</Name> <Value>8192</Value> </Attribute> <Attribute> <Name>MessageRetentionPeriod</Name> <Value>345600</Value> </Attribute> </GetQueueAttributesResult> <ResponseMetadata> <RequestId>1ea71be5-b5a2-4f9d-b85a-945d8d08cd0b</RequestId> </ResponseMetadata></GetQueueAttributesResponse>
Related Actions• SetQueueAttributes (p. 35)
API Version 2009-02-0124
Amazon Simple Queue Service API ReferenceGetQueueAttributes
ListQueues
DescriptionThe ListQueues action returns a list of your queues. The maximum number of queues that can bereturned is 1000. If you specify a value for the optional QueueNamePrefix parameter, only queues witha name beginning with the specified value are returned.
Important
The WSDL version you use for the request affects which queues are included in the response.Before the release of version 2008-01-01, you could use either of the available versions(2007-05-01 or 2006-04-01) for your ListQueues call and the response would include all yourqueues.
If you're now using one or both of the old versions and the 2008-01-01 version to create queues,you can't get a list of all your queues with a single call to ListQueues. Instead, you must calltwice: once using either the 2007-05-01 or 2006-04-01 version (which returns all queues youcreated with versions older than 2008-01-01), and once using the 2008-01-01 version (whichreturns only the queues created with the 2008-01-01 version). We did this because queuescreated with the older versions are not compatible with the 2008-01-01 version, and vice versa.
Request ParametersThe following table lists the special request parameters the ListQueues action uses in addition to thecommon request parameters all actions use (for more information, see Common Query Parameters (p. 5)).
RequiredDescriptionName
NoString to use for filtering the list results. Only those queues whosename begins with the specified string are returned.
Type: String
Constraints: Maximum 80 characters; alphanumeric characters,hyphens (-), and underscores (_) are allowed.
QueueNamePrefix
Response ElementsThe following table lists the response elements the ListQueues action returns in addition to the commonresponse elements all actions return (for more information, see Responses section in the Amazon SQSDeveloper Guide.
DescriptionName
The queue URL for a queue.The response can contain up to 1000 QueueUrlelements.
Type: String
Ancestor: ListQueuesResult
QueueUrl
Special ErrorsThe ListQueues action returns no special errors besides the common errors all actions return (for moreinformation, see Common Errors (p. 5)).
API Version 2009-02-0125
Amazon Simple Queue Service API ReferenceListQueues
ExamplesThe following example Query request returns the queues whose names begin with the letter "T".
Sample Request
http://sqs.us-east-1.amazonaws.com/?Action=ListQueues&QueueNamePrefix=t&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<ListQueuesResponse> <ListQueuesResult> <QueueUrl> http://sqs.us-east-1.amazonaws.com/123456789012/testQueue </QueueUrl> </ListQueuesResult> <ResponseMetadata> <RequestId> 725275ae-0b9b-4762-b238-436d7c65a1ac </RequestId> </ResponseMetadata></ListQueuesResponse>
Related Actions• CreateQueue (p. 14)
• DeleteQueue (p. 19)
API Version 2009-02-0126
Amazon Simple Queue Service API ReferenceListQueues
ReceiveMessage
DescriptionThe ReceiveMessage action retrieves one or more messages from the specified queue. For eachmessage returned, the response includes the following:
• Message body
• MD5 digest of the message body (for information about MD5, go to http://faqs.org/rfcs/rfc1321.html)
• Message ID you received when you sent the message to the queue
• Receipt handle
The receipt handle is the identifier you must provide when deleting the message (for more information,see Queue and Message Identifiers in the Amazon SQS Developer Guide).
Note
Due to the distributed nature of the queue, a weighted random set of machines is sampled on aReceiveMessage call. That means only the messages on the sampled machines are returned.If the number of messages in the queue is small (less than 1000), it is likely you will get fewermessages than you requested per ReceiveMessage call. If the number of messages in thequeue is extremely small, you might not receive any messages in a particular ReceiveMessageresponse; in which case you should repeat the request.
You can provide the VisibilityTimeout parameter in your request, which will be applied to themessages that SQS returns in the response. If you do not include the parameter, the overall visibilitytimeout for the queue is used for the returned messages. For more information, see Visibility Timeout inthe Amazon SQS Developer Guide.
Note
Some API operations take lists of parameters. These lists are specified using the param.nnotation.Values of n are integers starting from 1. For example, a parameter list with two elementslooks like this:
&Attribute.1=this&Attribute.2=that
Request ParametersThe following table lists the special request parameters the ReceiveMessage action uses in addition tothe common request parameters all actions use (for more information, see Common QueryParameters (p. 5)).
API Version 2009-02-0127
Amazon Simple Queue Service API ReferenceReceiveMessage
RequiredDescriptionName
NoThe attribute you want to get.
• All—returns all values.
• SenderId—returns the AWS account number (or the IPaddress, if anonymous access is allowed) of the sender.
• SentTimestamp—returns the time when the messagewas sent (epoch time in milliseconds).
• ApproximateReceiveCount—returns the number of timesa message has been received but not deleted.
• ApproximateFirstReceiveTimestamp—returns the timewhen the message was first received (epoch time inmilliseconds).
Type: String
Valid values: All | SenderId | SentTimestamp |ApproximateReceiveCount |ApproximateFirstReceiveTimestamp
Default: None
AttributeName.n
NoMaximum number of messages to return. SQS never returnsmore messages than this value but might return fewer.
Not necessarily all the messages in the queue are returned(for more information, see the preceding note about machinesampling).
Type: Integer from 1 to 10
Default: 1
MaxNumberOfMessages
NoThe duration (in seconds) that the received messages arehidden from subsequent retrieve requests after beingretrieved by a ReceiveMessage request.
Type: Integer
Constraints: 0 to 43200 (maximum 12 hours)
Default: The visibility timeout for the queue
VisibilityTimeout
Response ElementsThe following table lists the response elements the ReceiveMessage action returns in addition to thecommon response elements all actions return (for more information, see Responses section in the AmazonSQS Developer Guide.
API Version 2009-02-0128
Amazon Simple Queue Service API ReferenceReceiveMessage
DescriptionName
An element containing the information about the message.
Ancestor: ReceiveMessageResult
Children:
• Body—The message's contents (not URL encoded)
• MD5OfBody—An MD5 digest of the non-URL-encoded message bodystring
• MessageId—The message's SQS-assigned ID
• ReceiptHandle—A string associated with a specific instance of receivingthe message
• Attribute—SenderId, SentTimestamp, ApproximateReceiveCount, and/orApproximateFirstReceiveTimestamp. The SentTimestamp andApproximateFirstReceiveTimestamp are each returned as an integerrepresenting the epoch time in milliseconds.
Message
Special ErrorsThe following table lists the special errors the ReceiveMessage action returns in addition to the commonerrors all actions return (for more information, see Common Errors (p. 5)).
HTTP StatusCode
DescriptionError
400The value for MaxNumberOfMessages is not valid(must be from 1 to 10).
ReadCountOutOfRange
ExamplesThe following example Query request receives messages from the specified queue.
Sample Request
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=ReceiveMessage&MaxNumberOfMessages=5&VisibilityTimeout=15&AttributeName=All;&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
API Version 2009-02-0129
Amazon Simple Queue Service API ReferenceReceiveMessage
Sample Response
<ReceiveMessageResponse> <ReceiveMessageResult> <Message> <MessageId> 5fea7756-0ea4-451a-a703-a558b933e274 </MessageId> <ReceiptHandle> MbZj6wDWli+JvwwJaBV+3dcjk2YW2vA3+STFFljTM8tJJg6HRG6PYSasuWXPJB+Cw Lj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ+QE auMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0= </ReceiptHandle> <MD5OfBody> fafb00f5732ab283681e124bf8747ed1 </MD5OfBody> <Body>This is a test message</Body> <Attribute> <Name>SenderId</Name> <Value>195004372649</Value> </Attribute> <Attribute> <Name>SentTimestamp</Name> <Value>1238099229000</Value> </Attribute> <Attribute> <Name>ApproximateReceiveCount</Name> <Value>5</Value> </Attribute> <Attribute> <Name>ApproximateFirstReceiveTimestamp</Name> <Value>1250700979248</Value> </Attribute> </Message> </ReceiveMessageResult> <ResponseMetadata> <RequestId> b6633655-283d-45b4-aee4-4e84e0ae6afa </RequestId> </ResponseMetadata></ReceiveMessageResponse>
Related Actions• DeleteMessage (p. 17)
• SendMessage (p. 33)
• SetQueueAttributes (p. 35)
API Version 2009-02-0130
Amazon Simple Queue Service API ReferenceReceiveMessage
RemovePermission
DescriptionThe RemovePermission action revokes any permissions in the queue policy that matches the Labelparameter. Only the owner of the queue can remove permissions.
Request ParametersThe following table lists the special request parameters the action uses (in addition to the common requestparameters listed in Common Query Parameters (p. 5)).
RequiredDescriptionName
YesThe identfication of the permission you want to remove.This is the label you added in AddPermission (p. 10).Type: String (example: AliceSendMessage)
Default: None
Label
Response ElementsThe response contains no special elements besides the common elements listed in Responses sectionin the Amazon SQS Developer Guide.
Special ErrorsThe action returns no errors besides the common errors listed in Common Errors (p. 5).
ExamplesThe following example Query request removes the testLabel permission on the queue named testQueue.
Sample Request
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=RemovePermission&Label=testLabel&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<RemovePermissionResponse> <ResponseMetadata> <RequestId> f8bdb362-6616-42c0-977a-ce9a8bcce3bb </RequestId>
API Version 2009-02-0131
Amazon Simple Queue Service API ReferenceRemovePermission
</ResponseMetadata></RemovePermissionResponse>
Related Actions• AddPermission (p. 10)
API Version 2009-02-0132
Amazon Simple Queue Service API ReferenceRemovePermission
SendMessage
DescriptionThe SendMessage action delivers a message to the specified queue. The maximum allowed messagesize is 64 KB.
Important
The following list shows the characters (in Unicode) allowed in your message, according to theW3C XML specification (for more information, go to http://www.w3.org/TR/REC-xml/#charsets).If you send any characters not included in the list, your request will be rejected.
#x9 | #xA | #xD | [#x20 to #xD7FF] | [#xE000 to #xFFFD] | [#x10000 to #x10FFFF]
Request ParametersThe following table lists the special request parameters the SendMessage action uses in addition to thecommon request parameters all actions use (for more information, see Common Query Parameters (p. 5)).
RequiredDescriptionName
YesThe message to send.
Type: String maximum 64 KB in size. For a list of allowedcharacters, see the preceding important note.
MessageBody
Response ElementsThe following table lists the response elements the SendMessage action returns in addition to the commonresponse elements all actions return (for more information, see Responses section in the Amazon SQSDeveloper Guide.
DescriptionName
An MD5 digest of the non-URL-encoded message body string.You can usethis to verify that SQS received the message correctly. SQS first URL decodesthe message before creating the MD5 digest. For information about MD5, goto http://faqs.org/rfcs/rfc1321.html.
Type: String
Ancestor: SendMessageResult
MD5OfMessageBody
An element containing the message ID of the message sent to the queue.For more information, see Queue and Message Identifiers in the AmazonSQS Developer Guide.
Type: String
Ancestor: SendMessageResult
MessageId
Special ErrorsThe following table lists the special errors the SendMessage action returns in addition to the commonerrors all actions return (for more information, see Common Errors (p. 5)).
API Version 2009-02-0133
Amazon Simple Queue Service API ReferenceSendMessage
HTTP StatusCode
DescriptionError
400The message contains characters outside theallowed set.
InvalidMessageContents
400The message size cannot exceed 64 KB.MessageTooLong
Examples
Sample Request
The following example SendMessage request sends a message containing "Your Message Text" to thequeue.You must URL encode the entire URL; however, we've URL encoded only the message body tomake the example easier for you to read.
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=SendMessage&MessageBody=This+is+a+test+message&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
The following example response includes the MD5 digest for Your Message Text.
<SendMessageResponse> <SendMessageResult> <MD5OfMessageBody> fafb00f5732ab283681e124bf8747ed1 </MD5OfMessageBody> <MessageId> 5fea7756-0ea4-451a-a703-a558b933e274 </MessageId> </SendMessageResult> <ResponseMetadata> <RequestId> 27daac76-34dd-47df-bd01-1f6e873584a0 </RequestId> </ResponseMetadata></SendMessageResponse>
Related Actions• DeleteMessage (p. 17)
• ReceiveMessage (p. 27)
API Version 2009-02-0134
Amazon Simple Queue Service API ReferenceSendMessage
SetQueueAttributes
DescriptionThe SetQueueAttributes action sets one attribute of a queue per request.When you change a queue'sattributes, the change can take up to 60 seconds to propagate throughout the SQS system.
Request ParametersThe following table lists the special request parameters the SetQueueAttributes action uses in additionto the common request parameters all actions use (for more information, see Common QueryParameters (p. 5)).
RequiredDescriptionName
YesThe name of the attribute you want to set.
• VisibilityTimeout—The length of time (in seconds) that amessage received from a queue will be invisible to otherreceiving components when they ask to receive messages.For more information about VisibilityTimeout, seeVisibility Timeout in the Amazon SQS Developer Guide.
• Policy—The formal description of the permissions for aresource. For more information about Policy, see Basic PolicyStructure in the Amazon SQS Developer Guide.
• MaximumMessageSize—The limit of how many bytes amessage can contain before Amazon SQS rejects it.
• MessageRetentionPeriod—The number of seconds AmazonSQS retains a message.
Type: String
Valid Values: VisibilityTimeout | Policy |MaximumMessageSize | MessageRetentionPeriod
Default: None
Attribute.Name
API Version 2009-02-0135
Amazon Simple Queue Service API ReferenceSetQueueAttributes
RequiredDescriptionName
YesThe value of the attribute you want to set. To delete a queue'saccess control policy, set the policy to "".
Constraints: Constraints are specific for each value.
• VisibilityTimeout—An integer from 0 to 43200 (12 hours).
• Policy—A valid form-url-encoded policy. For more informationabout policy structure, see Basic Policy Structure in theAmazon SQS Developer Guide. For more information aboutform-url-encoding, seehttp://www.w3.org/MarkUp/html-spec/html-spec_8.html#SEC8.2.1.
• MaximumMessageSize—An integer from 1024 bytes (1KB)up to 65536 bytes (64KB).The default for this attribute is 8192(8KB).
• MessageRetentionPeriod—Integer representing seconds,from 3600 (1 hour) to 1209600 (14 days). The default for thisattribute is 345600 (4 days).
Default: Varies according to attribute
Attribute.Value
Response ElementsThe response contains no special elements besides the common elements in all successful responses(for more information, see Responses section in the Amazon SQS Developer Guide.
Special ErrorsThe following table lists the special errors the SetQueueAttributes action returns in addition to thecommon errors all actions return (for more information, see Common Errors (p. 5)).
HTTP StatusCode
DescriptionError
400Unknown attributeInvalidAttributeName
Examples
Sample Request with Policy
The following example Query request sets a policy that gives all users ReceiveMessage permission forthe queue named 195004372649/testQueue.
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=SetQueueAttributes&Version=2009-02-01&Attribute.Name=Policy&Attribute.Value=%7B%22Version%22%3A%222008-10-17%22%2C%22Id%22%3A%22%2F195004372649%2FtestQueue%2FSQSDefaultPolicy%22%2C%22Statement%22%3A%5B%7B%22Sid%22%3A%22Queue1ReceiveMessage%22%2C%22Effe
API Version 2009-02-0136
Amazon Simple Queue Service API ReferenceSetQueueAttributes
ct%22%3A%22Allow%22%2C%22Principal%22%3A%7B%22AWS%22%3A%22*%22%7D%2C%22Action%22%3A%22SQS%3AReceiveMessage%22%2C%22Resource%22%3A%22%2F195004372649%2FtestQueue%22%7D%5D%7D&Timestamp=2009-05-06T16%3A57%3A31.000Z&AWSAccessKeyId=0AZAVD7PQ3DCC3452ZG2&Signature=%2Bd7ZlPIdnb%2BhpEna2TgfwQjfGF8%3D
The above policy value is form-url-encoded from the following text:
{ "Version":"2008-10-17", "Id":"/195004372649/testQueue/SQSDefaultPolicy", "Statement": [ { "Sid":"Queue1ReceiveMessage", "Effect":"Allow", "Principal":{"AWS":"*"}, "Action":"SQS:ReceiveMessage", "Resource":"/195004372649/testQueue" } ] }
For more examples of policies, see Amazon SQS Policy Examples in the Amazon SQS Developer Guide.
Sample Request with VisibilityTimeout
The following example Query request sets the visibility timeout to 35 seconds for the queue named123456789012/testQueue.
http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/?Action=SetQueueAttributes&Attribute.Name=VisibilityTimeout&Attribute.Value=35&Version=2009-02-01&SignatureMethod=HmacSHA256&Expires=2009-04-18T22%3A52%3A43PST&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE
Sample Response
<SetQueueAttributesResponse> <ResponseMetadata> <RequestId> e5cca473-4fc0-4198-a451-8abb94d02c75 </RequestId> </ResponseMetadata></SetQueueAttributesResponse>
Related Actions• GetQueueAttributes (p. 21)
API Version 2009-02-0137
Amazon Simple Queue Service API ReferenceSetQueueAttributes
Glossary
Glossary
action The action is the activity the principal has permission to perform.Theaction is B in the statement "A has permission to do B to C where Dapplies." The action is just the operation in the request to SQS. Forexample, Jane sends a request to Amazon SQS withAction=ReceiveMessage. For more information, see SharedQueues in the Amazon SQS Developer Guide.
conditions The conditions are any restrictions or details about the permission.The condition is D in the statement "A has permission to do B to Cwhere D applies." Following are some of the common types ofconditions:
issuer The issuer is the person who writes a policy to grant permissions toa resource. The issuer (by definition) is always the resource owner.AWS does not permit SQS users to create policies for resources theydon't own. If John is the resource owner, AWS authenticates John'sidentity when he submits the policy he's written to grant permissionsfor that resource.
message ID An identifier you get when you send a message to the queue.
permission A permission allows or disallows access to a particular resource.Youcan state any permission like this: "A has permission to do B to Cwhere D applies." For example, Jane (A) has permission to readmessages (B) from John's Amazon SQS queue (C), as long as sheasks to receive only a maximum of 10 messages from the queue ata time (D). Whenever Jane sends a request to Amazon SQS to useJohn's queue, the service checks to see if she has permission and if
API Version 2009-02-0138
Amazon Simple Queue Service API Reference
the request satisfies the conditions John set forth in the permission.For more information, see Shared Queues in the Amazon SQSDeveloper Guide.
queue URL The URL uniquely identifying a queue.
policy A policy is the formal description of the permissions for a resource.The Access Policy Language distinguishes between a policy and astatement. A policy is the complete document that can contain manydifferent permissions for a given resource. A statement is thedescription of an individual permission.Therefore a policy can containmultiple statements. For example, a policy could specify that Janecan use John's queue (one statement), and Bob cannot use John'squeue (another statement).
principal The principal is the person or persons who receive the permission inthe policy. The principal is A in the statement "A has permission todo B to C where D applies." In a policy, you may set the principal to"anyone" (i.e., you can specify a wildcard to represent all people).You might do this, for example, if you don't want to restrict accessbased on the actual identity of the requester, but instead on someother identifying characteristic such as the requester's IP address.
Query This is a type of HTTP request that generally uses only the GET orPOST HTTP method and a query string with parameters.
receipt handle An identifier you get when you receive a message from the queue.You must provide this identifier when deleting the message from thequeue.
requester The requester is the person who sends a request to an AWS serviceand asks for access to a particular resource. The requester sends arequest to AWS that essentially says: "Can A do B to C where Dapplies?" In this question, the requester is A.
resource The resource is the object the principal is requesting access to. Theresource is C in the statement "A has permission to do B to C whereD applies."
Secret Access Key A key that Amazon Web Services (AWS) assigns to you when yousign up for an AWS account. Used for request authentication. Formore information, see Your AWS Account in the Amazon SQSDeveloper Guide.
visibility timeout The length of time (in seconds) that a message that has been receivedfrom a queue will be invisible to other receiving components whenthey ask to receive messages. During the visibility timeout, thecomponent that received the message usually processes the messageand then deletes it from the queue. For more information, see VisibilityTimeout in the Amazon SQS Developer Guide.
API Version 2009-02-0139
Amazon Simple Queue Service API Reference
Document History
This documentation is associated with the 2009-02-01 release of the Amazon Simple Queue Service.This guide was last updated on 04 October 2011.
The following table describes the important changes since the last release of the Amazon Simple QueueService API Reference.
Release DateDescriptionChange
08 August 2011Removed sections that discussed SOAP because SOAP access toAmazon SQS has been disabled. For more information, go toAnnouncement: Deprecating SOAP access for SQS in the AWSDiscussion Forums.
SOAP nolongersupported
30 June 2010Added MaximumMessageSize and MessageRetentionPeriodqueue attributes. For more information, seeSetQueueAttributes (p. 35).
New QueueAttributes
28 April 2010Amazon SQS now supports the Asia Pacific (Singapore) Region. Formore information, see the new WSDL Location and APIVersion (p. 3) section.
New Region
2 December2009
Created a new US endpoint for Amazon SQS. For more information,see WSDL Location and API Version (p. 3).
New Endpoint
API Version 2009-02-0140
Amazon Simple Queue Service API Reference
IndexAAction parameter, 5AddPermission, 10attributes, 21, 35AWS account number, 10AWSAccessKeyId parameter, 5
CCreateQueue, 14
DDeleteMessage, 17DeleteQueue, 19
Eerrors, 5Expires parameter, 5
GGetQueueAttributes, 21
LListQueues, 25
Mmessages
deleting, 17receiving, 27sending to queue, 33
Nnumber of messages in queue, 21
Qqueues
attributes of, 21, 35creating, 14deleting, 19listing, 25permissions, 10size, 21
RReceiveMessage, 27
SSendMessage, 33SetQueueAttributes, 35signatures
Signature parameter, 5SignatureMethod parameter, 5SignatureVersion parameter, 5
size of queue, 21
VVersion parameter, 5visibility timeout, 12, 21, 35
WWSDL location, 3
API Version 2009-02-0141
Amazon Simple Queue Service API Reference