Amazon Simple Queue Service
API Reference (API Version 2012-11-05)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

CreateQueue

Description

Creates a new queue, or returns the URL of an existing one. 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.

Note

If you delete a queue, you must wait at least 60 seconds before creating a queue with the same name.

You may pass one or more attributes in the request. If you do not provide a value for any attribute, the queue will have the default value for that attribute. Permitted attributes are the same that can be set using SetQueueAttributes.

Note

Use GetQueueUrl to get a queue's URL. GetQueueUrl requires only the QueueName parameter.

If you provide the name of an existing queue, along with the exact names and values of all the queue's attributes, CreateQueue returns the queue URL for the existing queue. If the queue name, attribute names, or attribute values do not match an existing queue, CreateQueue returns an error.

Note

Some API actions take lists of parameters. These lists are specified using the param.n notation. Values of n are integers starting from 1. For example, a parameter list with two elements looks like this:

&Attribute.1=this

&Attribute.2=that

Request Parameters

For information about the common parameters that all actions use, see Common Parameters.

Attribute.entry.N

A map of attributes with their corresponding values.

The following lists the names, descriptions, and values of the special request parameters the CreateQueue action uses:

  • DelaySeconds - The time in seconds that the delivery of all messages in the queue will be delayed. An integer from 0 to 900 (15 minutes). The default for this attribute is 0 (zero).
  • MaximumMessageSize - The limit of how many bytes a message can contain before Amazon SQS rejects it. An integer from 1024 bytes (1 KiB) up to 262144 bytes (256 KiB). The default for this attribute is 262144 (256 KiB).
  • MessageRetentionPeriod - The number of seconds Amazon SQS retains a message. Integer representing seconds, from 60 (1 minute) to 1209600 (14 days). The default for this attribute is 345600 (4 days).
  • Policy - The queue's policy. A valid form-url-encoded policy. For more information about policy structure, see Basic Policy Structure in the Amazon SQS Developer Guide. For more information about form-url-encoding, see http://www.w3.org/MarkUp/html-spec/html-spec_8.html#SEC8.2.1.
  • ReceiveMessageWaitTimeSeconds - The time for which a ReceiveMessage call will wait for a message to arrive. An integer from 0 to 20 (seconds). The default for this attribute is 0.
  • VisibilityTimeout - The visibility timeout for the queue. An integer from 0 to 43200 (12 hours). The default for this attribute is 30. For more information about visibility timeout, see Visibility Timeout in the Amazon SQS Developer Guide.

Type: String to String map

Valid Map Keys: Policy | VisibilityTimeout | MaximumMessageSize | MessageRetentionPeriod | ApproximateNumberOfMessages | ApproximateNumberOfMessagesNotVisible | CreatedTimestamp | LastModifiedTimestamp | QueueArn | ApproximateNumberOfMessagesDelayed | DelaySeconds | ReceiveMessageWaitTimeSeconds | RedrivePolicy

Required: No

QueueName

The name for the queue to be created.

Type: String

Required: Yes

Response Elements

The following element is returned in a structure named CreateQueueResult.

QueueUrl

The URL for the created Amazon SQS queue.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

QueueDeletedRecently

You must wait 60 seconds after deleting a queue before you can create another with the same name.

HTTP Status Code: 400

QueueNameExists

A queue already exists with this name. Amazon SQS returns this error only if the request includes attributes whose values differ from those of the existing queue.

HTTP Status Code: 400

Examples

The following example Query request creates a new queue named testQueue.

Sample Request

        
http://sqs.us-east-1.amazonaws.com/
?Action=CreateQueue
&QueueName=testQueue
&Attribute.1.Name=VisibilityTimeout
&Attribute.1.Value=40
&Version=2011-10-01
&SignatureMethod=HmacSHA256
&Expires=2011-10-18T22%3A52%3A43PST
&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE
&SignatureVersion=2
&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE

      

Sample Response

        
<CreateQueueResponse>
    <CreateQueueResult>
        <QueueUrl>
            http://&useast1-query;/123456789012/testQueue
        </QueueUrl>
    </CreateQueueResult>
    <ResponseMetadata>
        <RequestId>
            7a62c49f-347e-4fc4-9331-6e8e7a96aa73
        </RequestId>
    </ResponseMetadata>
</CreateQueueResponse>