有奖捉虫:云通信与企业服务文档专题,速来> HOT

接口描述

本接口(Subscribe)用于在用户某个主题下创建一个新订阅。

  • 外网接口请求域名:https://cmq-topic-{$region}.api.qcloud.com
  • 内网接口请求域名:http://cmq-topic-{$region}.api.tencentyun.com

上述域名中的{$region}需用具体地域替换:gz(广州)、sh(上海)、bj(北京)、shjr(上海金融)、szjr(深圳金融)、hk(中国香港)、cd(成都)、ca(北美)、usw(美西)、sg(新加坡)。公共参数中的 region 值要与域名的 region 值保持一致,如果出现不一致的情况,以域名的 region 值为准,将请求发往域名 region 所指定的地域。

注意:

任何时候(包括内测期间),如果使用外网域名产生公网下行流量,都会收取流量费用。 因此强烈建议服务在腾讯云上的用户使用内网域名,内网不会产生流量费用。

输入参数

以下请求参数列表仅列出了接口请求参数,其它参数见 公共请求参数 页面。

参数名称 是否必选 类型 描述
topicName String 主题名字,在单个地域同一账号下唯一。主题名称是一个不超过64个字符的字符串,必须以字母为首字符,剩余部分可以包含字母、数字和横划线-
subscriptionName String 订阅名字,在单个地域同一账号的同一主题下唯一。订阅名称是一个不超过64个字符的字符串,必须以字母为首字符,剩余部分可以包含字母、数字和横划线-
protocol String 订阅的协议,目前支持两种协议:HTTP、queue。使用 HTTP 协议,用户需自己搭建接受消息的 Web Server。使用 queue,消息会自动推送到 CMQ queue,用户可以并发地拉取消息。
endpoint String 接收投递消息的 endpoint,根据协议 protocol 区分:
(1)对于 HTTP,endpoint 必须以http://开头,host 可以是域名或 IP,endpoint 长度最大为500,目前推送服务不能推送到私有网络中,因此 endpoint 填写为私有网络域名或地址将接收不到推送的消息,目前支持推送到公网和基础网络。
(2)对于 queue,则填 queueName。
notifyStrategy String 向 endpoint 推送消息出现错误时,CMQ 推送服务器的重试策略。取值有两种:
(1)BACKOFF_RETRY,退避重试。每隔[19,29]s 重试一次,重试3次后,就把该消息丢弃,继续推送下一条消息。
(2)EXPONENTIAL_DECAY_RETRY,指数衰退重试。每次重试的间隔是指数递增的,例如开始 1s,后面是2s,4s,8s...由于 Topic 消息的周期是一天,所以最多重试一天就把消息丢弃。默认值是 EXPONENTIAL_DECAY_RETRY。
notifyContentFormat String 推送内容的格式。取值:(1)JSON。(2)SIMPLIFIED,即 raw 格式。如果 protocol 是 Queue,则取值必须为 SIMPLIFIED。如果 protocol 是 HTTP,两个值均可以,默认值是 JSON。
filterTag.n String 消息正文。消息标签(用于消息过滤)。标签数量不能超过5个,每个标签不超过16个字符。与 (Batch)PublishMessage 的 msgTag 参数配合使用,规则如下:
(1)如果 filterTag 没有设置,则无论 msgTag 是否有设置,订阅接收所有发布到 Topic 的消息。
(2)如果 filterTag 数组有值,则只有数组中至少有一个值在 msgTag 数组中也存在时(即 filterTag 和 msgTag 有交集),订阅才接收该发布到 Topic 的消息。
(3)如果 filterTag 数组有值,但 msgTag 没设置,则不接收任何发布到 Topic 的消息,可以认为是(2)的一种特例,此时 filterTag 和 msgTag 没有交集。规则整体的设计思想是以订阅者的意愿为主。
BindingKey String 订阅接收消息的过滤策略。BindingKey 数量不超过5个, 每个 BindingKey 长度不超过64字节,每个 BindingKey 最多含有15个“.”, 即最多16个词组。

输出参数

在成功情况下,所有的输出参数都会返回给用户;失败情况下,至少会有 code、 message、 requestId 返回。

参数名称 类型 描述
code Int 0:表示成功,others:错误,详细错误见下表。
message String 错误提示信息。
requestId String 服务器生成的请求 ID。出现服务器内部错误时,用户可提交此 ID 给后台定位问题。
codeDesc String 错误信息描述。

错误码

以下是接口特有错误码,如果您要查找的错误码不在其中,可能在 公共错误码 中。

错误代码 模块错误代码 英文提示 描述
4490 10470 subscribtion is already existed 同一个账户的同一个 Topic 下,同名订阅已经存在。
4500 10480 number of subscription has reached the limit 同一个 Topic 下的订阅数量超过限制,目前最大是100。
4000 10490 number of filterTag exceed limit filterTag 数量超过限制。目前最多是5个。
4000 10500 endpoint format error endpoint 格式错误。
可能的错误有:(1)url 包含空格;(2)HTTP 的 url 没有以 "http://" 开头;(3)非法 url;(4)protocol 与 endpoint 对应不上。
4000 10510 undefined protocol 未定义的协议。请检查拼写是否有误。
4000 10520 undefined notify retry stragety 未定义的消息推送重试策略。请检查拼写是否有误。
4000 10530 undefined notify content format 未定义的消息推送格式。请检查拼写是否有误。
4510 10570 url connot contain any blank characters url 不能包含空白字符。
4000 10580 subscription name format error 订阅名字格式错误。
4000 10620 subscription name format error 订阅名字格式错误。
4000 10630 illegal endpoint 非法 endpoint。
4000 10640 notifyContentFormat of protocol queue must be SIMPLIFIED 当 protocol 字段为 queue 时,notifyContentFormat 必须为 SIMPLIFIED
6050 10740 too many filterTag filterTag 太多,请检查参数设置。
4000 10670 too many filterTag filterTag 数量太多,请检查参数数量。

示例

输入:

 https://domain/v2/index.php?Action=Subscribe
 &topicName=test-topic-123
 &subscriptionName=test-subscription-123
 &protocol=http
 &endpoint=http://your_host/your_path 
 &<公共请求参数>

输出:

{
    "code": 0,
    "message": "",
    "requestId": "14534664555"
}