Creates a subscription to a topic.
Authorization information
By default, you can use only an Alibaba Cloud account to call this operation. You can call this operation as a Resource Access Management (RAM) user only after you grant the required permissions to the RAM user. The following table describes the authorization information of this operation. For more information, see Permission policies and examples.
Name | Value |
API | Subscribe |
Action | mns:Subscribe |
Resource | acs:mns:$region:$accountid:/topics/$topicName/subscriptions/$subscriptionName |
Usage notes
A subscription name can be up to 255 characters in length and contain letters, digits, and hyphens (-). It must start with a letter or 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.
Request body
The request body is in the XML format and includes the following parameters.
Parameter
Type
Required
Example
Description
Endpoint
String
Yes
http://example.com
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
String
No
important
The tag that is used to filter messages. Only messages that have the same tag can be pushed.
A tag is a string that can be up to 16 characters in length.
By default, no tag is specified to filter messages.
NotifyStrategy
Boolean
No
BACKOFF_RETRY
The retry policy that is applied if an error occurs during message delivery to the endpoint.
Default value: BACKOFF_RETRY.
NotifyContentFormat
Boolean
No
SIMPLIFIED
The format of the message that is pushed to the endpoint.
Default value: XML.
If you want to use Terraform to manage alicloud_message_service_subscription, configure the parameters that are described in the following table.
Parameter
Type
Required
Example
Description
TopicName
String
Yes
testTopic
The name of the topic.
SubscriptionName
String
Yes
testSubscription
The name of the subscription.
PushType
String
Yes
queue
The terminal type. Valid values:
http: HTTP
queue
mpush: mobile devices
alisms: Alibaba Cloud SMS
email
Endpoint
String
Yes
demoQueue
The endpoint that is used to receive messages. If you set the PushType parameter to queue, you must specify a queue name.
MessageTag
String
No
important
The tag that is used to filter messages. Only messages that have the same tag can be pushed.
A tag is a string that can be up to 16 characters in length.
By default, no tag is specified to filter messages.
NotifyStrategy
Boolean
No
BACKOFF_RETRY
The retry policy that is applied if an error occurs when MNS pushes messages to the endpoint.
Default value: BACKOFF_RETRY.
NotifyContentFormat
Boolean
No
SIMPLIFIED
The format of the message that is pushed to the endpoint.
Default value: XML.
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 already exists, errors may occur. For example, if the values of the parameters of two subscriptions are the same, the HTTP status code 204 is returned. Otherwise, the HTTP status code 409 is returned.
Operation-specific response headers
Parameter
Type
Example
Description
Location
String
http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName
The URL of the subscription that is created. Syntax: http://$AccountId.mns.{REGION}.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName.
For more information about other response headers, see Common parameters.
Response body
None.
Example
Sample request
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+FIEXA*****
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 response
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
Error codes
Error code | Error message | HTTP status code | Description |
SubscriptionNameLengthError | Subscription name length is out of range, should be between 1 and 255. | 400 | The error message returned because the subscription name is invalid. You must specify a valid name. |
SubscriptionNameInvalid | The subscription you provided is invalid. SubscriptionName should start with alpha or digit, and contain only alpha, digit or -. | 400 | The error message returned because the subscription name is invalid. You must specify a valid name. |
SubscriptionAlreadyExist | The subscription you want to create already exists. | 409 | The error message returned because the specified subscription has the same name as an existing subscription, but has different parameters from the existing subscription. |
EndpointInvalid | The endpoint you provided is invalid. | 400 | The error message returned because the specified endpoint is invalid. For more information, see Endpoint. |
InvalidArgument | The length of filter tag should be between 1 and 16. | 400 | The error message returned because the length of the tag exceeds the limit. You must specify a valid tag. |