Export (0) Print
Expand All

Create Queue

Updated: January 30, 2013

Creates a new queue. Once created, this queue’s resource manifest is immutable. This operation is idempotent. Repeating the create call, after a queue with same name has been created successfully, will result in a 409 Conflict error message.

 

Method Request URI HTTP version

PUT

https://management.core.windows.net/{subscription ID}/services/ServiceBus/Namespaces/{Namespace}/Queues/{Queue Path}

HTTP/1.1

The following table describes required and optional request headers.

 

Request Header Description

Content-Type

application/xml;type=entry;charset=utf-8

x-ms-version

2012-03-01

Note that the request also requires a client certificate. This certificate must match the certificate you uploaded for that particular subscription.

The following table describes the key elements of the request body:

 

Property Name Type Required Description

MaxQueueSizeInMegaBytes

Unsigned Integer

Required

This parameter specifies the maximum queue size in megabytes. Any attempt to enqueue a message that causes the queue to exceed this value will fail. Only user content counts towards this value. Settable at queue creation time and at runtime:

  • Range: 1–5*1024.

  • Default: 1*1024.

QueueSizeinBytes

Unsigned Integer

Read-only. Not required at creation.

This parameter reflects the actual bytes that messages in the queue currently occupy of the queue’s quota.

Range: 0 – MaxTopicSizeinMegaBytes

QueueDepth

Unsigned Integer

Read-only. Not required at creation.

This parameter shows the number of messages currently in the queue.

DefaultMessageTimeToLive

XML Datetime

Optional, default is 14 days.

Based on whether DeadLettering is enabled, if a message has been stored in the queue for more than the specified time, it is automatically moved to DeadLetterQueue or deleted. This value is overwritten by a TTL specified on the message if the message TTL is smaller than the TTL set on the queue. This value is immutable after the queue has been created:

  • Range: 1 second – 14 days.

  • Default: 14 days.

LockDuration

XML Datetime

Optional, default is 30 seconds.

This setting determines the amount of time in seconds in which a message should be locked for processing by a receiver. After this period, the message is unlocked and available for consumption by the next receiver. Settable only at queue creation time:

  • Range: 0–5 min. 0 means that the message is not locked.

  • Default: 30 seconds.

RequiresSession

Boolean

Optional

Settable only at queue creation time. If set to true, the queue will be session aware and only the SessionReceiver is supported. Session-aware queues are not supported through REST.

  • Default: False.

RequiresDuplicateDetection

Boolean

Optional

Settable only at queue creation time.

  • Default for durable queue: False.

EnableDeadLetteringOnMessageExpiration

Boolean

Optional

Settable only at queue creation time.

  • Default: False.

This field governs how the Service Bus handles a message with an expired TTL. If it is enabled and a message expires, the Service Bus moves the message from the queue into the queue’s dead-letter subqueue. If disabled, the message is permanently deleted from the queue.

DuplicateDetectionHistoryTimeWindow

Time Span

Optional.

A property that specifies the time span during which the Service Bus detects message duplication.

  • Range: 1 second–7 days.

  • Default: 10 minutes.

Status

String

Read-only. Not required at creation.

Can be one of the following values:

  1. Creating: when still in creation phase.

  1. Active: by default after creation, or when user activates it after last time suspended.

  1. Suspended: when user updates the entity to be suspended.

The response includes an HTTP status code and a set of response headers.

noteNote
If you create a queue with a name that contains special or encoded characters (for example, "test?Name=value&", which gets encoded to "test%3FName%3Dvalue%26", a “(400) Invalid request” exception is generated.

 

Code Description

201

Queue created.

400

Invalid request body.

401

Authorization failure.

403

Quota exceeded; queue not created.

409

The specified queue already exists (or the specified path is already occupied).

500

Internal error.

For information about status codes, see Status and Error Codes.

The queue description is returned. If they were missing from the PUT request, some description properties might contain default values.

Show:
© 2014 Microsoft