文档首页/ 消息通知服务 SMN/ API参考/ API/ 订阅操作/ 订阅
更新时间：2024-04-19 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群机器人传输协议。

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

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

错误码

请参见错误码。

父主题： 订阅操作