文档首页/ 消息通知服务 SMN/ API参考（联盟区域）/ API/ 订阅操作/ 订阅
更新时间：2025-12-30 GMT+08:00
在线调试
CLI示例
查看PDF
分享

订阅

功能介绍

为指定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群机器人传输协议。

“dingTalkBot”：个人钉钉传输协议。

endpoint

是

String

说明：

http协议，接入点必须以“http://”开头，且必须为公网的IPV4地址、IPV6地址或域名地址。不支持使用内网地址，包括但不限于IPv4私有地址、IPv6本地地址、回环地址等。需确保该地址可通过公网路由访问，避免因防火墙、NAT或DNS配置导致不可达。

https协议，接入点必须以“https://”开头，且必须为公网的IPV4地址、IPV6地址或域名地址。不支持使用内网地址，包括但不限于IPv4私有地址、IPv6本地地址、回环地址等。需确保该地址可通过公网路由访问，避免因防火墙、NAT或DNS配置导致不可达。

email协议，接入点必须是邮件地址。

sms协议，接入点必须是一个电话号码。

functionstage协议，接入点必须是一个函数。

functiongraph协议，接入点必须是一个函数工作流。

callnotify协议，接入点必须是一个电话号码。

dingding协议，接入点必须是一个钉钉自定义群机器人的地址，或添加了钉钉企业内部机器人的群组openConversationId。添加钉钉企业内部机器人对应的群组openConversationId时，该字段不能以“http://”或“https://”为开头。

wechat协议，接入点必须是一个微信群机器人的地址。

feishu协议，接入点必须是一个飞书群机器人的地址。

welink协议，接入点必须是一个welink的群号。

dingTalkBot协议，接入点必须是一个钉钉企业用户的userId。

remark

否

String

备注。最大支持128字节，约42个中文，必须是UTF-8编码的字符串，否则无法正常显示中文。

extension

否

SubscriptionExtension object

扩展信息。

subscriptions

否

Array of BatchAddSubscriptionsRequestBody objects

当需要批量创建订阅时，需要传入该字段。SMN支持一次最多创建50个订阅。
表4 BatchAddSubscriptionsRequestBody

参数

是否必选

参数类型

描述

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协议，接入点必须是一个函数工作流。

callnotify协议，接入点必须是一个电话号码。

dingding协议，接入点必须是一个钉钉自定义群机器人的地址，或添加了钉钉企业内部机器人的群组openConversationId。添加钉钉企业内部机器人对应的群组openConversationId时，该字段不能以“http://”或“https://”为开头。

wechat协议，接入点必须是一个微信群机器人的地址。

feishu协议，接入点必须是一个飞书群机器人的地址。

welink协议，接入点必须是一个welink的群号。

remark

否

String

备注。最大支持128字节，约42个中文，必须是UTF-8编码的字符串，否则无法正常显示中文。

extension

否

SubscriptionExtension object

订阅的扩展信息。
表5 SubscriptionExtension

参数

是否必选

参数类型

描述

client_id

否

String

这是应用ID字段。当protocol值为welink时，该字段为必填字段，从welink方获取。

client_secret

否

String

该字段为应用secret字段。当protocol值为welink时，该字段为必填字段，从welink方获取。

keyword

否

String

该字段为关键字字段。当protocol值为feishu时，这里的keyword字段和sign_secret字段二者必选其一。当用户在飞书或钉钉自定义机器人端添加关键字校验的安全策略时，这里的关键字必须是飞书或钉钉自定义机器人中所填写的关键字之一。

sign_secret

否

String

这是加签密钥字段。当protocol协议为feishu时，这个字段和keyword字段二者必选且只能选其一。密钥配置必须与客户在飞书或钉钉自定义机器人的密钥配置完全一致。例如，如果在飞书端配置了密钥并且没有配置关键字，则在此处填入从飞书获取的密钥字段，如果在飞书端没有配置密钥并且配置了关键字，则不填写该字段。

header

否

Map<String,String>

该字段为http header字段，用户可以在字段限制范围内自定义http header，header字段内容以KV对形式存在。当使用主题发送时，已确认的订阅发送消息会携带用户自定义的http header。

header应满足如下要求：

key值限定为：包含英文字母([A-Za-z])、数字([0-9])、中划线(-)hyphens，中划线不得作为结尾，不得连续出现。

K/V不得超过10个

key需要以"x-"开头，不能以"x-smn"开头，正确示例：x-abc-cba, x-abc

所有K/V长度总和不得超过1024个字符

key不区分大小写

key值不可重复

value值限定为ASCII码，不支持中文或其他Unicode，支持空格

app_key

否

String

个人钉钉appKey字段，字符长度限制64个，仅支持字母、数字、中划线(-)、下划线(_)。当订阅协议为dingTalkBot时，该字段必选。

app_secret

否

String

个人钉钉appSecret字段，字符长度限制128个，仅支持字母、数字、中划线(-)、下划线(_)。当订阅协议为dingTalkBot时，该字段必选。

robot_code

否

String

个人钉钉robotCode字段，名称：机器人编码，字符长度限制64个，仅支持字母、数字、中划线(-)、下划线(_)，一般与appKey一致。当订阅协议为dingTalkBot时，该字段必选。

响应参数

状态码：201

表6 响应Body参数

参数

参数类型

描述

request_id

String

请求的唯一标识ID。

subscription_urn

String

订阅者的唯一资源标识。

状态码：400

表7 响应Body参数

参数

参数类型

描述

request_id

String

请求的唯一标识ID。

code

String

服务异常错误信息编码。

message

String

服务异常错误信息描述。

状态码：403

表8 响应Body参数

参数

参数类型

描述

request_id

String

请求的唯一标识ID。

code

String

服务异常错误信息编码。

message

String

服务异常错误信息描述。

error_code

String

服务异常错误信息编码。

error_msg

String

服务异常错误信息描述。

encoded_authorization_message

String

编码 (加密) 后的详细拒绝原因。

details

OpenAPIFailedDetails object

云服务调用依赖服务得到的异常信息详情。
表9 OpenAPIFailedDetails

参数

参数类型

描述

error_code

String

云服务调用依赖服务响应中携带的 异常错误信息编码。

error_msg

String

云服务调用依赖服务响应中携带的 异常错误信息描述。

状态码：404

表10 响应Body参数

参数

参数类型

描述

request_id

String

请求的唯一标识ID。

code

String

服务异常错误信息编码。

message

String

服务异常错误信息描述。

状态码：500

表11 响应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@example.com",
  "remark" : "运维"
}

响应示例

状态码：201

OK

[ {
  "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

错误码

请参见错误码。

父主题： 订阅操作