edit-icon download-icon

Subscription APIs

Last Updated: Mar 31, 2017

Subscribe

Description

This API is used to create a subscription to a topic.

A subscription name is a string of no more than 256 characters, including letters, numbers, and hyphens (-). It must start with a letter or number.

An endpoint must be specified for the created subscription; otherwise, the subscription is invalid.

Request

A request includes the following parts:

  • Request line

    PUT /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1 .

  • Special request header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    The request body is in XML format and contains the created subscription attributes.

Parameter name Description Parameter value Required/Optional
Endpoint Terminal address of the message recipient for the created subscription Currently, four types of endpoints are supported: 1. HttpEndpoint, which must be prefixed with “http://“; 2. QueueEndpoint, in the format of acs:mns:{REGION}:{AccountID}:queues/{QueueName}; 3. MailEndpoint, in the format of mail:directmail:{MailAddress}; 4. SmsEndpoint, in the format of sms:directsms:anonymous or sms:directsms:{Phone}. Required
FilterTag Message filter tag in the created subscription (Only messages with consistent tags are pushed.) The value is a string of no more than 16 characters. The default value is no message filter. Optional
NotifyStrategy Retry policy that will be applied when an error occurs during message push to the endpoint BACKOFF_RETRY or EXPONENTIAL_DECAY_RETRY; default value:BACKOFF_RETRY. For details about retry policies, refer to Basic Concepts/NotifyStrategy. Optional
NotifyContentFormat Format of the message content pushed to the endpoint XML, JSON, or SIMPLIFIED; default value: XML. For details about message formats, refer to Basic Concepts/NotifyContentFormat. Optional

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 201

    Duplicate subscription names are not allowed for the same subscriber of the same topic. If the created subscription has the same name and attributes as an existing subscription, Status Code 204 (No Content) is returned; if only the names are the same but the attributes are different, Status Code 409 (Conflict) is returned.

  • Special response header

Parameter name Description
Location Returned URL of the successfully created subscription, in the following format: http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName

For the other response headers, refer to Call Method/Public Parameters.

  • Response Body

    None

Special Error

Error code Error message Status code
SubscriptionNameLengthError Subscription name length is out of range, should be between 1 and 256. 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

Request example:

  1. PUT /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 06:06:46 GMT
  4. Authorization:MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
  5. x-mns-version: 2015-06-06
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Subscription xmlns="http://mns.aliyuncs.com/doc/v1/">
  8. <Endpoint>http://company.com</Endpoint>
  9. <NotifyStrategy>BACKOFF_RETRY</NotifyStrategy>
  10. <NotifyContentFormat>SIMPLIFIED</NotifyContentFormat>
  11. <FilterTag>important</FilterTag>
  12. </Subscription>

Response example:

  1. HTTP/1.1 201
  2. x-mns-request-id:56667376B2B71C9C16000025
  3. x-mns-version: 2015-06-06
  4. Location: http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName

SetSubscriptionAttributes

Description

This API is used to modify subscription attributes.

Request

A request includes the following parts:

  • Request line

    PUT /topics/$TopicName/subscriptions/$SubscriptionName?metaoverride=true HTTP/1.1

  • Special URI parameter

    metaoverride=true: The attributes of the subscription will be modified.

  • Special request header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    The request body is in XML format and contains the modified subscription attributes.

Parameter name Description Parameter value Required/Optional
NotifyStrategy Retry policy that will be applied when an error occurs during message push to the endpoint BACKOFF_RETRY or EXPONENTIAL_DECAY_RETRY; default value:BACKOFF_RETRY. For details about retry policies, refer to Basic Concepts/NotifyStrategy. Optional

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 204 No Content

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    None

Special Error:

Error code Error message Status code
SubscriptionNotExist The subscription you provided does not exits. 404

Request example:

  1. PUT /topics/$TopicName/subscriptions/$SubscriptionName?metaoverride=true HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 06:09:22 GMT
  4. Authorization: MNS 15B4D3461F177624206A:rNT4xclLS297/n0UFYIezzHJI7Q=
  5. x-mns-version: 2015-06-06
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Subscription xmlns="http://mns.aliyuncs.com/doc/v1/">
  8. <NotifyStrategy>BACKOFF_RETRY</ NotifyStrategy>
  9. </Subscription>

Response example:

  1. HTTP/1.1 204 No Content
  2. x-mns-request-id:56667412B2B71C9C16000027
  3. x-mns-version: 2015-06-06

GetSubscriptionAttributes

Description

This API is used to obtain subscription attributes.

Request

A request includes the following parts:

  • Request line

    GET /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1

  • Special request header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    None

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 200 OK

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

Parameter name Description
SubscriptionName Name of the subscription
Subscriber Account ID of the subscriber
TopicOwner Account ID of the owner of the subscribed topic
TopicName Name of the subscribed topic
Endpoint Terminal address of the subscriber
NotifyStrategy Retry policy that will be applied when an error occurs during message push to the endpoint
NotifyContentFormat Format of the message content pushed to the endpoint
FilterTag Message filter tag in the subscription (Only messages with consistent tags are pushed.)
CreateTime Time when a subscription is created, defined as the number of seconds that have elapsed since 00:00:00, January 1, 1970
LastModifyTime Last modification time of subscription attributes, defined as the number of seconds that have elapsed since 00:00:00, January 1, 1970

Special Error

Error code Error message Status code
SubscriberNotExist The subscription you provided does not exist. 404

Request example:

  1. GET /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 06:09:58 GMT
  4. Authorization: MNS 15B4D3461F177624206A:GvaApggLQfMu6B6W5sbF6HEjV6Y=
  5. x-mns-version: 2015-06-06

Response example:

  1. HTTP/1.1 200 OK
  2. Content-Type=text/xml;utf-8
  3. Content-Length:451
  4. x-mns-request-id:56667436B2B71C9C16000029
  5. x-mns-version: 2015-06-06
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Subscription xmlns="http://mns.aliyuncs.com/doc/v1">
  8. <CreateTime>1449554806</CreateTime>
  9. <Endpoint>http://company.com</Endpoint>
  10. <FilterTag>important</FilterTag>
  11. <LastModifyTime>1449554962</LastModifyTime>
  12. <NotifyContentFormat>XML</NotifyContentFormat>
  13. <NotifyStrategy>BACKOFF_RETRY</NotifyStrategy>
  14. <SubscriptionName>$SubscriptionName</SubscriptionName>
  15. <Subscriber>$Subscriber</Subscriber>
  16. <TopicName>$TopicName</TopicName>
  17. <TopicOwner>$TopicOwner</TopicOwner>
  18. </Subscription>

Unsubscribe

Description

This API is used to cancel a subscription.

Request

A request includes the following parts:

  • Request line

    DELETE /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1

  • Special request header

    None. For details, refer to Call method/Public parameters.

  • Request Body None

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 204 No Content

    If the subscription to be canceled does not exist, Status Code 204 is returned and the Unsubscribe operation is successful.

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    None

Request example:

  1. DELETE /topics/$TopicName/Subscriptions/$SubscriptionName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 06:18:04 GMT
  4. Authorization: MNS 15B4D3461F177624206A:UOEb7OmC9GX7G9BLY3XryP6vtjQ=
  5. x-mns-version: 2015-06-06

Response example:

  1. HTTP/1.1 204 No Content
  2. x-mns-request-id: 5666761CB2B71C9C16000035
  3. x-mns-version: 2015-06-06

ListSubscriptionByTopic

Description

This API is used to list the subscriptions to a topic. Querying by page is supported.

TIP:

If the total number of subscriptions returned for the current request exceeds the x-mns-ret-number value, the returned XML results include NextMarker to indicate the starting position of the next page, and this value is assigned to the x-mns-marker parameter in the next request to display the next page.

Request

A request includes the following parts:

  • Request line

    GET /topics/$TopicName/subscriptions HTTP/1.1

  • Special request header

Parameter name Description Required/Optional
x-mns-prefix Search for the subscription names starting with the specified prefix Optional
x-mns-marker Starting position of the next page, which is acquired from NextMarker on the previous page Optional
x-mns-ret-number Maximum number of subscriptions returned for a single request, which is an integer in the range of 1 to 1,000. The default value is 1,000. Optional

For the other request headers, refer to Call Method/Public Parameters.

  • Request Body

    None

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 200 OK

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    The returned results are in XML format. The top-layer Subscriptions element contains multiple Subscription elements, and each Subscription element contains the SubscriptionURL element indicating the URL of the subscription.If the number of returned queues exceeds the x-mns-ret-number value, the NextMarker element is included to indicate the starting position of the next page.

Request example:

  1. GET /topics/$TopicName/subscriptions HTTP/1.1
  2. x-mns-ret-number:2
  3. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  4. Date: Tue, 08 Dec 2015 06:16:18 GMT
  5. Authorization: MNS 15B4D3461F177624206A:dXSLY5yGG8Ri5f26ZEmxMCq1CC4=
  6. x-mns-version: 2015-06-06

Response example:

  1. HTTP/1.1 200 OK
  2. x-mns-request-id:566675B2B2B71C9C16000033
  3. x-mns-version: 2015-06-06
  4. <?xml version="1.0" encoding="utf-8"?>
  5. <Subscriptions xmlns="http://mns.aliyuncs.com/doc/v1/">
  6. <Subscription>
  7. <SubscriptionURL>http://$AccountId.mns.cn-hangzhou.aliyuncs.com/$TopicName/subscriptions/$SubscriptionName1</SubscriptionURL>
  8. </Subscription>
  9. <Subscription>
  10. <SubscriptionURL>http://$AccountId.mns.cn-hangzhou.aliyuncs.com/$TopicName/subscriptions/$SubscriptionName2</SubscriptionURL>
  11. </Subscription>
  12. <NextMarker>OTczNjU4MTcvYmRwejd6NXluby8yNjg0Mi9+fn5FI1Rlc3RUb3BpYy0xI2JkcHo3ejV5bm8jVGVzdFN1Yi0zLzA=</NextMarker>
  13. </Subscriptions>
Thank you! We've received your feedback.