文档首页/ 设备接入 IoTDA/ API参考/ 应用侧API参考/ API/ 广播消息/ 下发广播消息 - BroadcastMessage
更新时间：2025-12-02 GMT+08:00
查看PDF
分享

下发广播消息 - BroadcastMessage

功能介绍

应用服务器可调用此接口向订阅了指定Topic的所有在线设备发布广播消息。应用将广播消息下发给平台后，平台会先返回应用响应结果，再将消息广播给设备。

注意：

  • 此接口只适用于使用MQTT协议接入的设备。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    访问级别

    资源类型（*为必须）

    条件键

    别名

    依赖的授权项

    iotda:message:broadcast

    Write

    app *

    -

    -

    -

    -

    g:EnterpriseProjectId

URI

POST /v5/iot/{project_id}/broadcast-messages

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数说明：项目ID。获取方法请参见 获取项目ID。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Instance-Id

否

String

参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考 查看实例详情。
表3 请求Body参数

参数

是否必选

参数类型

描述

app_id

否

String

参数说明：资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，建议携带该参数指定广播消息所属的资源空间，否则广播消息将会向默认资源空间下订阅指定topic的设备发送。

取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。

topic_full_name

是

String

参数说明：接收广播消息的完整Topic名称, 必选。用户需要发布广播消息给设备时，可以使用该参数指定完整的topic名称，物联网平台会向指定资源空间下订阅了该topic的所有在线设备发送消息。广播的topic无需控制台创建，但topic的前缀必须为$oc/broadcast/

message

是

String

参数说明：广播消息的内容，用户需要将消息原文使用Base64编码。请求参数体最大长度为256KB。

ttl

否

Integer

参数说明：广播消息在平台缓存的老化时间，时间单位是分钟，默认值为0, 即默认不缓存消息；ttl>0时表示缓存消息，ttl参数数值必须是5的倍数，即以5分钟为粒度，最大缓存时间为1440分钟；ttl>0时，一个topic订阅设备数限制为10，如果一个topic订阅设备数超过10，则接口返回错误。

message_id

否

String

参数说明：消息id，由用户生成（推荐使用UUID）。ttl> 0时，平台会缓存消息，需确保message_id是唯一的， 否则接口返回错误。

取值范围：最大长度为128，只允许字母、数字、下划线（_）、连接符（-）的组合。

响应参数

状态码：201

表4 响应Body参数

参数

参数类型

描述

app_id

String

参数说明：资源空间ID。

topic_full_name

String

参数说明：接收广播消息的完整Topic名称

message_id

String

消息id，由物联网平台生成，用于标识该消息。

created_time

String

消息的创建时间，"yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串。

请求示例

下发广播消息。

POST https://{endpoint}/v5/iot/{project_id}/broadcast-messages

{
  "topic_full_name" : "$oc/broadcast/test",
  "message" : "SGVsbG9Xb3JsZA=="
}

响应示例

状态码：201

Created

{
  "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka",
  "topic_full_name" : "$oc/broadcast/test",
  "message_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
  "created_time" : "20151212T121212Z"
}

状态码

状态码

描述

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

错误码

请参见错误码。

父主题： 广播消息