Creates a topic.

Authorization

By default, only Alibaba Cloud accounts can call this operation. RAM users can call this operation only after these RAM users are granted related permissions. The following table describes the authorization information of this operation. For more information, see Permission policies and examples.

Item Value
API operation CreateTopic
Action mns:CreateTopic
Resource acs:mns:$region:$accountid:/topics/$topicName

Limits

The name of the topic is a string that can be a maximum of 255 characters in length and can contain letters, digits, and hyphens (-). It must start with a letter or digit.

Request

A request consists of the following parts:

  • Request line

    PUT /topics/$TopicName HTTP/1.1

  • Operation-specific request headers

    None.

  • Request body

    The request body is in the XML format. It contains the following parameters that are used to create a topic.

    Parameter Type Required Example Description
    MaximumMessageSize Integer No 10240 The maximum size of a message body that can be sent to the topic.

    Valid values: 1024 to 65536. Unit: bytes.

    Default value: 65536.

    LoggingEnabled Boolean No True Specifies whether to enable the log management feature.
    Valid values:
    • True: enables the log management feature.
    • False: disables the log management feature.

    Default value: False.

Response

A response consists of the following parts:

  • HTTP status code

    HTTP/1.1 201 Created

    The name of each topic must be unique in a region within an Alibaba Cloud account. If you create a topic whose name already exists, errors may occur. For example, if the parameters of the two topics are the same, the error code 204 (No Content) is returned. If the parameters of the two topics are different, the error code 409 (Conflict) is returned.

  • Operation-specific response headers
    Parameter Type  Example Description
    Location String http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName The URL of the topic that was created. Syntax: http://$AccountId.mns.<Region>.aliyuncs.com/topics/$TopicName.

    For more information about common response headers, see Common parameters.

  • Response body

    None.

Examples

Sample requests

PUT /topics/$TopicName HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Tue, 08 Dec 2015 05:57:57 GMT
x-mns-version: 2015-06-06
Authorization:MNS 15B4D3461F177624206A:eCtaUwfGS0oEfznzJEhWFxpf****

<?xml version="1.0" encoding="utf-8"?>
<Topic xmlns="http://mns.aliyuncs.com/doc/v1/">
    <MaximumMessageSize>10240</MaximumMessageSize>
    <LoggingEnabled>True</LoggingEnabled>
</Topic>
            

Sample success responses

HTTP/1.1 201 Created
x-mns-request-id:56667165B2B71C9C1600****
x-mns-version: 2015-06-06
Location: http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName
            

Error codes

Error code Error message HTTP status code Description
TopicAlreadyExist The topic you want to create is already exists. 409 The error message returned because the specified topic has the same name as an existing topic, but has different parameters from the existing topic.
TopicNameLengthError Topic name length is out of range, should be between 1 and 255. 400 The error message returned because the specified topic name is invalid.