本文导读

功能介绍
调用方法
URI
请求参数
响应参数
请求示例
响应示例
状态码
错误码

展开导读

文档首页/ 消息通知服务 SMN/ API参考（安卡拉区域）/ API/ 订阅操作/ 订阅

为指定Topic添加一个订阅者，如果订阅者的状态为未确认，则向订阅者发送一个确认的消息。待订阅者进行ConfirmSubscription确认后，该订阅者才能收到Topic发布的消息。单Topic默认可添加10000个订阅者，高并发场景下，可能会出现订阅者数量超过10000仍添加成功的情况，此为正常现象。接口是幂等的，如果添加已存在的订阅者，则返回成功，且status code为200，否则status code为201。

调用方法

请参见如何调用API。

URI

POST /v2/{project_id}/notifications/topics/{topic_urn}/subscriptions

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	项目ID。获取项目ID请参考获取项目ID。
topic_urn	是	String	Topic的唯一的资源标识，可通过查询主题列表获取该标识。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。

表3 请求Body参数
参数	是否必选	参数类型	描述
protocol	是	String	不同协议对应不同的endpoint（接受消息的接入点）。目前支持的协议包括： “email”：邮件传输协议，endpoint为邮箱地址。 “sms”：短信传输协议，endpoint为手机号码。 “functionstage”：FunctionGraph（函数）传输协议，endpoint为一个函数。 “functiongraph”：FunctionGraph（工作流）传输协议，endpoint为由一组函数编排成的工作流。 “http”、“https”：HTTP/HTTPS传输协议，endpoint为URL。 “callnotify”：语音通知传输协议，endpoint为手机号码。 “wechat”：微信群机器人传输协议。 “dingding”：钉钉群机器人传输协议。 “feishu”：飞书群机器人传输协议。 “welink”：welink群机器人传输协议。
endpoint	是	String	说明： http协议，接入点必须以“http://”开头。 https协议，接入点必须以“https://”开头。 email协议，接入点必须是邮件地址。 sms协议，接入点必须是一个电话号码。 functionstage协议，接入点必须是一个函数。 functiongraph协议，接入点必须是一个函数工作流。 dms协议，接入点必须是一个消息队列。 application协议，接入点必须是一个应用平台的设备终端。 callnotify协议，接入点必须是一个电话号码。 dingding协议，接入点必须是一个钉钉自定义群机器人的地址，或添加了钉钉企业内部机器人的群组openConversationId。添加钉钉企业内部机器人对应的群组openConversationId时，该字段不能以“http://”或“https://”为开头。 wechat协议，接入点必须是一个微信群机器人的地址。 feishu协议，接入点必须是一个飞书群机器人的地址。 welink协议，接入点必须是一个welink的群号。
remark	否	String	备注。最大支持128字节，约42个中文，必须是UTF-8编码的字符串，否则无法正常显示中文。
extension	否	SubscriptionExtension object	扩展信息。

表4 SubscriptionExtension
参数	是否必选	参数类型	描述
client_id	否	String	这是应用ID字段。当protocol值为welink时，该字段为必填字段，从welink方获取。最小长度：1 最大长度：64
client_secret	否	String	该字段为应用secret字段。当protocol值为welink时，该字段为必填字段，从welink方获取。最小长度：1 最大长度：64
keyword	否	String	该字段为关键字字段。当protocol值为feishu时，这里的keyword字段和sign_secret字段二者必选其一。当用户在飞书或钉钉自定义机器人端添加关键字校验的安全策略时，这里的关键字必须是飞书或钉钉自定义机器人中所填写的关键字之一。最小长度：0 最大长度：20
sign_secret	否	String	这是加签密钥字段。当protocol协议为feishu时，这个字段和keyword字段二者必选且只能选其一。密钥配置必须与客户在飞书或钉钉自定义机器人的密钥配置完全一致。例如，如果在飞书端配置了密钥并且没有配置关键字，则在此处填入从飞书获取的密钥字段，如果在飞书端没有配置密钥并且配置了关键字，则不填写该字段。最小长度：0 最大长度：256

响应参数

状态码： 201

表5 响应Body参数
参数	参数类型	描述
request_id	String	请求的唯一标识ID。
subscription_urn	String	订阅者的唯一资源标识。

状态码： 400

表6 响应Body参数
参数	参数类型	描述
request_id	String	请求的唯一标识ID。
code	String	服务异常错误信息编码。
message	String	服务异常错误信息描述。

状态码： 403

表7 响应Body参数
参数	参数类型	描述
request_id	String	请求的唯一标识ID。
code	String	服务异常错误信息编码。
message	String	服务异常错误信息描述。

状态码： 404

表8 响应Body参数
参数	参数类型	描述
request_id	String	请求的唯一标识ID。
code	String	服务异常错误信息编码。
message	String	服务异常错误信息描述。

状态码： 500

表9 响应Body参数
参数	参数类型	描述
request_id	String	请求的唯一标识ID。
code	String	服务异常错误信息编码。
message	String	服务异常错误信息描述。

请求示例

在名称为test_topic_v1的主题下添加一个邮件订阅者

POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1/subscriptions

{
  "protocol" : "email",
  "endpoint" : "xxx@xxx.com",
  "remark" : "运维"
}

响应示例

状态码： 201

[ {
  "request_id" : "6a63a18b8bab40ffb71ebd9cb80d0085",
  "subscription_urn" : "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837"
} ]

状态码

状态码	描述
201	OK
400	Bad Request
403	Unauthorized
404	Not Found
500	Internal Server Error

错误码

请参见错误码。

父主题： 订阅操作

上一篇：查询指定Topic的订阅者列表

下一篇：取消订阅

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消