Create Topic

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

Please note the following:

  • The topic is not immediately deleted. It is marked for deletion and the resource management agent retrieves this deletion request within 5 minutes. However, the UI should reflect this operation immediately according to the received HTTP code.

  • The topic name is actually the URI path. The following regular expression validates each segment in the URI path after removing possible % encoding.

  • The topic name should comply with the following RegEx.

    public static readonly Regex SafeMessagingEntityNameExpression = new Regex(@"^[\w-\.\$]*/?$", RegexOptions.Compiled | RegexOptions.ECMAScript);

    This means the following:

    • Entity segments can contain only letters, numbers, periods (.), hyphens (-), and underscores (_).

    • Multiple segments are allowed (for example, if queue name = “a/b/c”, it contains three segments).

    • Forward slash (/) is not allowed as a prefix or suffix of the queue name.

    • Maximum number of characters is 50.

Request

Method Request URI HTTP version
PUT https://management.core.windows.net/{subscription ID}/services/ServiceBus/Namespaces/{Namespace}/Topics/{Topic Path} HTTP/1.1

Request Headers

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.

Request Body

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

Property Name Type Required Description
MaxTopicSizeInMegaBytes Unsigned Integer Required. This parameter specifies the maximum topic size in megabytes. Any attempt to enqueue a message that causes the topic to exceed this value will fail. Only user content counts towards this value. Settable at topic creation time and at runtime:

- Range: 1–51024.

- Default: 1\
1024.
TopicSizeinBytes Unsigned Integer Read only. Not required at creation time. This parameter reflects the actual number of bytes that messages in the topic currently occupy relative to the topic quota.

Range: 0 – MaxTopicSizeinMegaBytes
DefaultMessageTimeToLive XML Datetime Optional. Based on whether dead lettering is enabled, if a message has been stored in the topic for more than the specified time, it is automatically moved to the dead letter queue 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 topic. This value is immutable after the topic has been created:

- Range: 1 second – 14 days.

- Default: 14 days.
RequiresDuplicateDetection Boolean Optional. Settable only at topic creation time.

- Default for durable topic: False.
EnableDeadLetteringOnMessageExpiration Boolean Optional. Settable only at topic creation time.

- Default: False.

This field determines how Service Bus handles a message with an expired TTL. If it is enabled and a message expires, Service Bus moves the message from the topic into the dead-letter subqueue for that topic. If disabled, the message is permanently deleted from the topic.
DuplicateDetectionHistoryTimeWindow Time Span Optional. A property that specifies the time span during which Service Bus detects message duplication.

- Range: 1 second – 7 days.

- Default: 10 minutes.
NumberOfSubscriptions Integer Read only. Not required at creation time. Number of topic subscriptions.
Status String Read only. One of the following values:

- Creating: when still in the creation phase.
- Active: by default after creation, or when the user activates it after last time suspended.
- Suspended: when the user updates the entity to be suspended.

Response

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

Response Codes

Note

If you create a topic with a name that contains special or encoded characters (for example, test?Name=value&, which is encoded to test%3FName%3Dvalue%26), a (401) Unauthorized exception is generated.

Code Description
201 Topic created successfully.
400 Invalid request body.
401 Authorization failure.
403 Quota exceeded; queue not updated.
500 Internal error.

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

Response Headers

Response Header Description
Content-Type application/xml;type=entry;charset=utf-8

Response Body

The topic description is returned, because if some description properties were missing from the PUT request, they might contain default values.