All Products
Search
Document Center

Message Service:Subscribe

Last Updated:Mar 11, 2024

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 the RAM users are granted the related permissions. 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

Item

acs:mns:$region:$accountid:/topics/$topicName/subscriptions/$subscriptionName

Description

  • 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.

  • 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 by the subscriber to receive messages. Syntax: <account_id>.mns.<region_id>.aliyuncs.com.

    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 when MNS pushes messages to the endpoint.

    Valid values:

    • BACKOFF_RETRY: retries with a fixed backoff interval.

    • EXPONENTIAL_DECAY_RETRY: retries with an exponential backoff interval.

    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. The following table describes the parameters.

    Parameter

    Type

    Required

    Example

    Description

    TopicName

    String

    Yes

    testTopic

    The name of the MNS 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 by the subscriber 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: retries with a fixed backoff interval.

    • EXPONENTIAL_DECAY_RETRY: retries with an exponential backoff interval.

    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.

Error message

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.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 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. 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.