Creates a subscription to 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 Subscribe
Action mns:Subscribe
Resource acs:mns:$region:$accountid:/topics/$topicName/subscriptions/$subscriptionName

Description

  • 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. The request body includes the following parameters.

    Parameter Type Required Example Description
    Endpoint String Yes http://example.com The endpoint that the subscriber uses to receive messages. Syntax: acs:mns:{REGION}:{AccountID}:queues/{QueueName}.
    FilterTag String No important The tag that is used to filter messages. Only the 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: retries with a fixed backoff interval.
    • EXPONENTIAL_DECAY_RETRY: retries with exponential backoff.
    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

    In a topic, each subscription name must be unique. If you create a subscription that already exists, errors may occur. For example, if the parameters of two subscriptions are the same, the HTTP status code 204 is returned. If the parameters of the two subscriptions are different, 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.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName.

    For more information about common 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+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 success 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

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. Modify the name as suggested.
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. Modify the name as suggested.
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 is invalid. Modify the tag.