接口描述
本接口（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"
}
