消息服务的Subscription如何操作？

Subscribe



描述

该接口用于订阅主题，创建 Subscription。Subscription 名称是一个不超过 256 个字符的字符串，必须以字母或者数字为首字符，剩余部分可以包含字母、数字和横华线(-)。创建Subscription 时，需要指定对应的 Endpoint，否则不合法。

Request

Request 的构造主要由以下几部分组成：

• 
  请求行

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

• 
  特有 Request Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Request Body

  
  Request Body 为 XML 格式，XML 总包含创建 Subscription 的属性。

参数名称	说明	参数值	选项
Endpoint	描述此次订阅中接收消息的终端地址	目前四种Endpoint: 1. HttpEndpoint，必须以”http://"为前缀 2. QueueEndpoint, 格式为acs:mns:{REGION}:{AccountID}:queues/{QueueName} 3. MailEndpoint, 格式为mail:directmail:{MailAddress} 4. SmsEndpoint, 格式为sms:directsms:anonymous 或sms:directsms:{Phone}	Required
FilterTag	描述了该订阅中消息过滤的标签（标签一致的消息才会被推送）	不超过16个字符的字符串，默认不进行消息过滤	Optional
NotifyStrategy	描述了向 Endpoint 推送消息出现错误时的重试策略	BACKOFF_RETRY 或者 EXPONENTIAL_DECAY_RETRY，默认为BACKOFF_RETRY，重试策略的具体描述请参考 [backcolor=transparent]基本概念/NotifyStrategy	Optional
NotifyContentFormat	描述了向 Endpoint 推送的消息格式	XML 、JSON 或者 SIMPLIFIED，默认为 XML，消息格式的具体描述请参考 [backcolor=transparent]基本概念/NotifyContentFormat	Optional

Response

返回消息由返回状态行、HTTP头和消息体三部分组成

• 
  HTTP Status Code

  
  HTTP/1.1 201同一个订阅者在同一个主题下的 Subscription 不能重名，当出现重名时，如果正在创建的 Subscription 已经存在的 Subscription 属性完全相同，返回 204，否则返回 409 (Conflict)。

• 
  特有 Response Header

参数名称	说明
Location	返回创建成功的 SubscriptionURL，格式如下：http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName

其它 Response Header 请参考 [backcolor=transparent]调用方式/公共参数

• Response Body

  
  无

Special Error

错误代码	错误信息	状态码
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

[tr=rgb(239, 251, 255)][td]EndpointInvalid The endpoint you provided is invalid.400 InvalidArgumentThe length of filter tag should be between 1 and 16.400
[backcolor=transparent]请求示例：
[backcolor=transparent]


SetSubscriptionAttributes



描述

该接口用于修改 Subscription 的属性

Request

Request 的构造主要由以下几个部分组成：

• 
  请求行

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

• 
  特有 URI 参数

  
  metaoverride=true 将会修改 Subscription 的属性

• 
  特有 Request Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Request Body

  
  Request Body 为 XML 格式，XML 中包含修改 Subscription 的属性：

参数名称	说明	参数值	选项
NotifyStrategy	描述了向 Endpoint 推送消息出现错误时的重试策略	BACKOFF_RETRY 或者 EXPONENTIAL_DECAY_RETRY，默认为BACKOFF_RETRY，重试策略的具体描述请参考 [backcolor=transparent]基本概念/NotifyStrategy	Optional

Response

返回消息由返回状态行、HTTP头和消息体三部分

• 
  HTTP Status Code

  
  HTTP/1.1 204 No Content

• 
  特有 Response Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Response Body

  
  无

Special Error:

错误代码	错误消息	状态码
SubscriptionNotExist	The subscription you provided does not exits.	404

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]


GetSubscriptionAttributes



描述

该接口用于获取 Subscription 的属性

Request

Request 的构造主要由以下几个部分组成：

• 
  请求行

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

• 
  特有 Request Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Request Body

  
  无

Response

返回消息由返回状态行、HTTP头和消息三部分组成

• 
  HTTP Status Code

  
  HTTP/1.1 200 OK

• 
  特有 Response Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Response Body

参数名称	说明
SubscriptionName	Subscription 的名称
Subscriber	Subscription 订阅者的 AccountId
TopicOwner	Subscription 订阅的主题所有者的 AccountId
TopicName	Subscription 订阅的主题名称
Endpoint	订阅的终端地址
NotifyStrategy	向 Endpoint 推送消息错误时的重试策略
NotifyContentFormat	向 Endpoint 推送的消息内容格式
FilterTag	描述了该订阅中消息过滤的标签（仅标签一致的消息才会被推送）
CreateTime	Subscription 的创建时间，从 1970-1-1 00:00:00 到现在的秒值
LastModifyTime	修改 Subscription 属性信息最近时间，从 1970-1-1 00:00:00 到现在的秒值

Special Error

错误代码	错误信息	状态码
SubscriberNotExist	The subscription you provided does not exist.	404

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]


Unsubscribe



描述

该接口用于取消一个已创建的 Subscription。

Request

Request 的构造主要由以下几个部分组成：

• 
  请求行

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

• 
  特有 Request Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Request Body

  
  无

Response

返回消息由返回状态行、HTTP头和消息体三部分组成

• 
  HTTP Status Code

  
  HTTP/1.1 204 No Content如果 Unsubscribe 的 Subscription 不存在，返回 204，取消订阅成功

• 
  特有 Response Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Response Body

  
  无

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]


ListSubscriptionByTopic



描述

该接口用于列出某个主题下的 Subscription 列表，可分页获取数据。

[backcolor=transparent]Tips：

如果本次请求结果返回的 Subscription 总数超过本次请求的 x-mns-ret-number 参数值，返回的 XML 结果中包含的 NextMarker 表示下一页开始位置，在下一次请求时将该值赋予 x-mns-marker 参数以返回下一页的结果。

Request

Request 的构造主要由以下几个部分组成：

• 
  请求行

  
  GET /topics/$TopicName/subscriptions HTTP/1.1

• 
  特有 Request Header

参数名称	说明	选项
x-mns-prefix	按照该前缀开头的 SubscriptionName 进行查找	Optional
x-mns-marker	请求下一个分页的开始位置，从上次分页结果返回的 NextMarker 获取	Optional
x-mns-ret-number	单次请求结果的最大返回个数，1 - 1000 范围内的整数值，默认值为 1000	Optional

其它 Request Header 请参考 [backcolor=transparent]调用方式/公共参数

• Request Body

  
  无

Response

返回消息由返回状态行、HTTP头和消息体三部分组成

• 
  HTTP Status Code

  
  HTTP/1.1 200 OK

• 
  特有 Response Header

  
  无，请参考 [backcolor=transparent]调用方式/公共参数

• 
  Response Body

  
  返回 XML 格式的结果，顶层 Subscriptions 元素下包含多个 Subscription 元素，Subscription 元素中包含 SubscriptionURL，SubscriptionURL 表示 Subscription 的 URL 访问地址。如果返回结果超过 x-mns-ret-number 的参数值，包含 NextMarker 元素表示下个分页的起始位置。

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]