文档

Subscribe

更新时间:

调用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://example.com

    目前四种Endpoint:

    • HttpEndpoint:必须以http://为前缀。

    • QueueEndpoint:格式为acs:mns:{REGION}:{AccountID}:queues/{QueueName}。

    • MailEndpoint:格式为mail:directmail:{MailAddress}。

    • SmsEndpoint:格式为sms:directsms:anonymous 或sms:directsms:{Phone}。

    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。

    如果您使用Terraform管理alicloud_message_service_subscription,请按照下表说明对参数进行调用。

    参数名称

    类型

    是否必选

    示例值

    描述

    TopicName

    String

    testTopic

    主题名称。

    SubscriptionName

    String

    testSubscription

    订阅名称。

    PushType

    String

    queue

    终端类型。

    • http:HTTP推送类型。

    • queue:队列推送类型。

    • mpush:移动推送类型。

    • alisms:阿里短信推送类型。

    • email:邮箱推送类型。

    Endpoint

    String

    demoQueue

    此次订阅中接收消息的终端地址。终端是队列则填写队列名。

    MessageTag

    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.{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://example.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

过滤标签长度不符合要求,请按照建议调整。

  • 本页导读 (1)