Creates a subscription.
Description
You can call this operation to create a subscription. A subscription name can be up to 255 characters in length and can contain letters, digits, and hyphens (-). The name must start with a letter or a digit.
You must specify an endpoint when you create a subscription. Otherwise, the subscription is invalid.
Request
A request consists of the following parts:
Request line
PUT /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1
Operation-specific request headers
None. For more information about common request headers, see Common parameters.
Request body
The request body is in the XML format and includes the following parameters.
Parameter
Required
Description
Value
Endpoint
Yes
The endpoint that is used to receive messages.
You can specify the following types of endpoints:
HttpEndpoint. An HTTP endpoint must start with http://.
QueueEndpoint. Syntax: acs:mns:{REGION}:{AccountID}:queues/{QueueName}.
MailEndpoint. Syntax: mail:directmail:{MailAddress}.
SmsEndpoint. Syntax: sms:directsms:anonymous or sms:directsms:{Phone}.
FilterTag
No
The tag that is used to filter messages. Only the messages that have the same tag can be pushed.
A tag can be up to 16 characters in length. By default, no tag is specified to filter messages.
NotifyStrategy
No
The retry policy that is applied if an error occurs during message delivery to the endpoint.
Valid values: BACKOFF_RETRY and EXPONENTIAL_DECAY_RETRY. Default value: BACKOFF_RETRY. For more information, see NotifyStrategy.
NotifyContentFormat
No
The format of the message that is pushed to the endpoint.
Valid values: XML, JSON, and SIMPLIFIED. Default value: XML. For more information, see NotifyContentFormat.
Response
A response consists of the following parts:
HTTP status code
HTTP/1.1 201
Each subscription name must be unique in a topic. If you create a subscription that has the same name as an existing subscription, the following errors may occur: If the subscription that you want to create has the same parameter values as the existing subscription, the HTTP status code 204 is returned. If the parameter values of the two subscriptions are different, the HTTP status code 409 is returned.
Operation-specific response headers
Parameter
Description
Location
The URL of the subscription that is created. Syntax: http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName.
For more information about other response headers, see Common parameters.
Response body
None.
Examples
Sample requests
PUT /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Tue, 08 Dec 2015 06:06:46 GMT
Authorization:MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+****AMPLE=
x-mns-version: 2015-06-06
<?xml version="1.0" encoding="utf-8"?>
<Subscription xmlns="http://mns.aliyuncs.com/doc/v1/">
<Endpoint>http://example.com</Endpoint>
<NotifyStrategy>BACKOFF_RETRY</NotifyStrategy>
<NotifyContentFormat>SIMPLIFIED</NotifyContentFormat>
<FilterTag>important</FilterTag>
</Subscription>
Sample responses
HTTP/1.1 201
x-mns-request-id:56667376B2B71C9C1600****
x-mns-version: 2015-06-06
Location: http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName
Special errors
Error code | Error message | Status code |
SubscriptionNameLengthError | Subscription name length is out of range, should be between 1 and 255. | 400 |
SubscriptionNameInvalid | The subscription you provided is invalid. SubscriptionName should start with alpha or digit, and contain only alpha, digit or -. | 400 |
SubscriptionAlreadyExist | The subscription you want to create already exists. | 409 |
EndpointInvalid | The endpoint you provided is invalid. | 400 |
InvalidArgument | The length of filter tag should be between 1 and 16. | 400 |