调用Subscribe接口,为主题创建Subscription。

授权信息

默认仅限阿里云账号使用本接口,RAM用户只有在被授予了相关API操作权限后方可使用。本接口的授权信息如下表所示。更多信息,请参见授权策略和示例

Name Value
API Subscribe
RAM授权操作 mns:Subscribe
资源 acs:mns:$region:$accountid:/topics/$topicName/subscriptions/$subscriptionName

使用说明

  • Subscription名称是一个不超过255个字符的字符串,必须以字母或者数字为首字符,剩余部分可以包含字母、数字和短划线(-)。
  • 创建Subscription时,需要指定对应的Endpoint,否则不合法。

请求消息

请求消息由请求行、HTTP头和消息体三部分组成:

  • 请求行

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

  • 特有Request Header

    无。

  • Request Body

    Request Body为XML格式,XML中包含创建Subscription的属性。

    参数名称 类型 是否必选 示例值 描述
    Endpoint String http://company.com 此次订阅中接收消息的终端地址。格式为acs:mns:{REGION}:{AccountID}:queues/{QueueName}。
    FilterTag String important 该订阅中消息过滤的标签(标签一致的消息才会被推送)。

    取值范围:不超过16个字符的字符串。

    默认不进行消息过滤。

    NotifyStrategy Boolean BACKOFF_RETRY 向Endpoint推送消息出现错误时的重试策略。
    取值范围:
    • BACKOFF_RETRY:退避重试
    • EXPONENTIAL_DECAY_RETRY:指数衰减重试
    重试策略的具体描述,请参见NotifyStrategy

    默认值:BACKOFF_RETRY。

    NotifyContentFormat Boolean SIMPLIFIED 用于定义向Endpoint推送的消息格式。
    取值范围:
    • XML
    • JSON
    • SIMPLIFIED
    消息格式的具体描述,请参见NotifyContentFormat

    默认值:XML。

返回消息

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

  • HTTP Status Code

    HTTP/1.1 201

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

  • 特有Response Header
    参数名称 类型 示例值 描述
    Location String http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName 返回创建成功的SubscriptionURL,格式如下:http://$AccountId.mns.cn-{REGION}.aliyuncs.com/topics/$TopicName/subscriptions/$SubscriptionName。

    其他Response Header,请参见公共参数

  • Response Body

    无。

示例

请求示例:

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://company.com</Endpoint>
    <NotifyStrategy>BACKOFF_RETRY</NotifyStrategy>
    <NotifyContentFormat>SIMPLIFIED</NotifyContentFormat>
    <FilterTag>important</FilterTag>
</Subscription>

返回示例:

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

错误码

错误码 错误信息 HTTP状态码 描述内容
SubscriptionNameLengthError Subscription name length is out of range, should be between 1 and 255. 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 Endpoint参数不合法,请参见Endpoint
InvalidArgument The length of filter tag should be between 1 and 16. 400 过滤标签长度不符合要求,请按照建议调整。