文档首页/ 消息通知服务 SMN/ API参考（联盟区域）/ API/ 发布消息操作/ 消息发布

更新时间：2025-12-30 GMT+08:00

查看PDF

消息发布

功能介绍

将消息发送给Topic的所有订阅端点。当返回消息ID时，该消息已被保存并开始尝试将其推送给Topic的订阅者。为确保您的消息能够成功推送到各个订阅者，请确保您的消息内容符合当地法律法规要求。

三种消息发送方式

message

message_structure

message_template_name

只需要设置其中一个，如果同时设置，生效的优先级为

message_structure > message_template_name > message。

若发布消息的主题下绑定了KMS密钥，请确保发布消息前，用户需要先在IAM处创建名为smn_kms_agency的委托，并将资源操作权限授权给SMN服务。当发布消息时，SMN会使用该委托进行创建数据密钥和解密数据密钥操作。

调用方法

请参见如何调用API。

URI

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

表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参数
参数	是否必选	参数类型	描述
subject	否	String	消息标题，给邮箱订阅者发送邮件时作为邮件主题，长度不能超过512个字节。
message	否	String	发送的消息。消息体必须是UTF-8编码的字符串，大小至多256KB。如果订阅者是手机号码，短信长度限制为490字，超出则可能被运营商拦截。短信内容不能包含“[]”或者“【】”符号。说明：三种消息发送方式：message、message_structure、message_template_name至少设置其中一个，如果同时设置，生效的优先级为message_structure > message_template_name > message。
message_structure	否	String	Json格式的字符串。支持“email”、“sms”、“http”、“https”、“functiongraph”、“functionstage”、“dingding”、“wechat”、“feishu”、“welink”、“dingTalkBot”。必须设置默认的消息“default”，当匹配不到消息协议时，按“default”中的内容发送。 - 其中，钉钉、微信、飞书、welink、dingTalkBot协议类型的消息需指定msgType字段；钉钉，微信和飞书机器人协议支持msgType为text（纯文本）和markdown（MD）格式消息，welink机器人类型暂仅支持msgType为text的纯文本消息。 - 企业微信机器人对消息长度的限制请参考官方文档。 - 钉钉机器人协议支持通过at字段实现@群组成员。当您需要@群成员时，可以在isAtAll字段中传入布尔值，表示是否需要@群组内所有人。您可以在atMobiles字段中传入需要@的人的手机号列表，或在atUserIds字段中传入需要@的钉钉userID列表。当您使用atMobiles字段或atUserIds字段时，需要在消息内容中同时传入@对应手机号或userID的信息。展示效果请参考钉钉官方文档。钉钉群机器人消息限制在20000bytes以内，详情请参考钉钉官方文档描述。- 飞书机器人协议的markdown消息支持通过传入color字段设置标题的底色。能够支持的color字段可参考飞书官方文档。飞书群机器人消息限制在30KB以内，详情请参考飞书官方文档描述。 - 个人钉钉消息对长度的限制请参考官方文档。说明：三种消息发送方式：message、message_structure、message_template_name至少设置其中一个，如果同时设置，生效的优先级为message_structure > message_template_name > message。
message_template_name	否	String	消息模板名称，可通过查询消息模板列表获取名称。说明：三种消息发送方式：message、message_structure、message_template_name至少设置其中一个，如果同时设置，生效的优先级为message_structure > message_template_name > message。
tags	否	Map<String,String>	tag以及替换tag的参数组成的字典。消息模板中的标签对应的值。使用消息模板方式的消息发布必须携带该参数。字典中的key为消息模板中的参数名称，不超过21个字符。字典中的value为消息模板中的参数被替换后的值，不超过1KB。
time_to_live	否	String	指消息在SMN系统内部的最长存留时间。超过该存留时间，系统将不再发送该消息。单位是s，变量默认值是3600s，即一小时。值为正整数且小于等于3600*24。
message_attributes	否	Array of MessageAttribute objects	消息属性列表
locale	否	String	语言，发送出去的消息中SMN附加系统内容的语言，若没传入，使用账号的语言。取值范围是该局点支持的语言，比如：zh-cn,en-us等

表4 MessageAttribute
参数	是否必选	参数类型	描述
name	是	String	属性名称。属性名称只能包含小写英文字母([a-z])、数字([0-9])、下划线(_)，下划线不能出现在开始或结尾，下划线不能连续出现，长度为1到32个字符
type	是	String	属性类型 STRING：字符串（String）类型 STRING_ARRAY：字符串数组（String.Array）类型 PROTOCOL：协议类型
value	是	Object	属性值。当属性类型为“STRING”时，属性值只能包含中英文、数字、下划线，长度为1到32个字符。当属性类型为“STRING_ARRAY”时，属性值为字符串数组，数组长度为1到10，数组中的元素内容不能重复，数组中的每个字符串都只能包含中英文、数字、下划线，且长度为1到32个字符。当属性类型为“PROTOCOL”时，属性值为支持协议类型的字符串数组。

响应参数

状态码：200

表5 响应Body参数
参数	参数类型	描述
request_id	String	请求的唯一标识ID。
message_id	String	唯一的消息ID。

状态码：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	服务异常错误信息描述。

状态码：429

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

状态码：500

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

请求示例

消息发布

POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:test_create_topic_v2/publish

{
  "subject" : "test message v2",
  "message" : "Message test message v2",
  "time_to_live" : "3600",
  "message_attributes" : [ {
    "name" : "smn_protocol",
    "type" : "PROTOCOL",
    "value" : [ "email", "sms" ]
  } ]
}

使用消息结构体方式的消息发布

POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:test_create_topic_v2/publish

{
  "subject" : "test message v2",
  "message_structure" : "{   \"default\": \"Message structure test message v2\",   \"sms\": \"Message structure test message v2\",   \"email\": \"Message structure test message v2\",   \"wechat\": \"{\\\"msgtype\\\":\\\"text\\\",\\\"text\\\":{\\\"content\\\":\\\"Message structure test message v2\\\"}}\",   \"dingding\": \"{\\\"msgtype\\\":\\\"markdown\\\",\\\"at\\\":{\\\"atMobiles\\\": [\\\"15XXXXXX\\\"],\\\"atUserIds\\\": [\\\"1234567XXX\\\"],\\\"isAtAll\\\": true},\\\"markdown\\\":{\\\"content\\\":\\\"Message structure test message v2 @15XXXXXX @1234567XXX\\\",\\\"title\\\":\\\"Message structure title\\\"}}\",   \"feishu\": \"{\\\"msgtype\\\":\\\"text\\\",\\\"text\\\":{\\\"content\\\":\\\"Message structure test message v2\\\"}}\",   \"welinkRed\": \"{\\\"msgtype\\\":\\\"text\\\",\\\"text\\\":{\\\"content\\\":\\\"Message structure test message v2\\\"}}\",   \"http\": \"Message structure test message v2\",   \"https\": \"Message structure test message v2\",   \"dingTalkBot\": \"{\\\"msgtype\\\":\\\"markdown\\\",\\\"markdown\\\":{\\\"content\\\":\\\"Message structure test message v2 dingTalkBot markdown\\\",\\\"title\\\":\\\"Message structure title\\\"}}\",   \"functionstage\": \"Message structure test message v2\" }",
  "time_to_live" : "3600",
  "message_attributes" : [ {
    "name" : "smn_protocol",
    "type" : "PROTOCOL",
    "value" : [ "email", "sms" ]
  } ]
}

使用消息模板方式的消息发布

POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:test_create_topic_v2/publish

{
  "subject" : "test message template v2",
  "message_template_name" : "confirm_message",
  "time_to_live" : "3600",
  "tags" : {
    "topic_urn" : "topic_urn3331",
    "topic_id" : "topic_id3332"
  },
  "message_attributes" : [ {
    "name" : "smn_protocol",
    "type" : "PROTOCOL",
    "value" : [ "email", "sms" ]
  } ]
}

响应示例

状态码：200

{
  "request_id" : "6a63a18b8bab40ffb71ebd9cb80d0085",
  "message_id" : "bf94b63a5dfb475994d3ac34664e24f2"
}

状态码

状态码	描述
200	OK
400	Bad Request
403	Unauthorized
404	Not Found
429	Too Many Requests
500	Internal Server Error

错误码

请参见错误码。

父主题： 发布消息操作

上一篇：发布消息操作

下一篇：发布探测消息

消息发布

功能介绍

调用方法

URI

请求参数

响应参数

请求示例

响应示例

状态码

错误码

您对此文档页面的整体评价？