:Subscribe

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.

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. Valid values: BACKOFF_RETRY EXPONENTIAL_DECAY_RETRY For more information, see NotifyStrategy. Default value: BACKOFF_RETRY.
  NotifyContentFormat	Boolean	No	SIMPLIFIED	The format of the message that is pushed to the endpoint. Valid values: XML JSON SIMPLIFIED For more information, see NotifyContentFormat. 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. Valid values: BACKOFF_RETRY EXPONENTIAL_DECAY_RETRY For more information, see NotifyStrategy. Default value: BACKOFF_RETRY.
  NotifyContentFormat	Boolean	No	SIMPLIFIED	The format of the message that is pushed to the endpoint. Valid values: XML JSON SIMPLIFIED For more information, see NotifyContentFormat. 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