Pub
Publishes a message to a device by using a custom topic. You can call this operation to broadcast messages to the online devices of a specific product. The online devices subscribe to a specific custom topic.
Usage notes
When you call this operation to broadcast messages, take note of the following items:
-
When you configure a device, you must write code to define a topic. You do not need to create a topic in the IoT Platform console.
-
By default, you can subscribe to a topic for up to 1,000 devices.
Limits
You cannot call this operation to send commands to configure device properties or call device services.
-
To configure device properties, call the SetDeviceProperty or SetDevicesProperty operation.
-
To call device services, call the InvokeThingService or InvokeThingsService operation.
Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| Action | String | Yes | Pub | The operation that you want to perform. Set the value to Pub. |
| ProductKey | String | Yes | a1Q5XoY**** | The ProductKey of the product to which the device that receives the message belongs. |
| MessageContent | String | Yes | eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0= | The body of the message that you want to publish. To generate a message body, convert the raw message into binary data and perform Base64 encoding. Note IoT Platform decodes data by using the Base64 algorithm and then sends the decoded message to the device. This way, the device does not need to decode the Base64 encoded data. |
| TopicFullName | String | Yes | /a1Q5XoY****/device1/user/get | The custom topic for the device that receives the message. - If you use an MQTT gateway device, the original custom topic of the device is used as the custom topic. - If you use a non-MQTT gateway device, the custom topic is in one of the following formats: - /${productKey}/${deviceName}/user/${TopicShortName}: The system sends a message to a specific device that belongs to a product whose ProductKey is specified by the ${productKey} variable.- /broadcast/${productKey}/${Custom field}: The system sends a message to the online devices of a product whose ProductKey is specified by the ${productKey} variable. The online devices subscribe to the custom topic. Replace ${productKey} with the ProductKey of the product whose devices receive the message. The ${Custom field} variable specifies a custom field.Important - The topic must have the Subscribe or Publish and Subscribe permission. - Before you call the Pub operation, make sure that the device subscribes to the topic. Otherwise, the device cannot receive the message. To query custom topics, use one of the following methods: - Call the QueryProductTopic operation to query the custom topics of a product. - On the Topic Categories tab of the details page of a product, view the custom topics of the product. - On the Topic List tab of the details page of a device, view the custom topics to which the device subscribes. |
| Qos | Integer | No | 0 | The quality of service (QoS) level of the message. Valid values: - 0: The system sends the message at most once. - 1: The system sends the message at least once. If a PUBACK response is not returned after you publish a QoS 1 message, the message is pushed to the device again when the device reconnects to IoT Platform. Default value: 0. |
In addition to the preceding operation-specific request parameters, you must configure common request parameters when you call this operation. For more information about common request parameters, see Common parameters.
Response parameters
| Parameter | Type | Example | Description |
|---|---|---|---|
| Code | String | iot.system.SystemException | The error code that is returned if the call fails. For more information about the error codes, see Error codes. |
| ErrorMessage | String | A system exception occurred. | The error message that is returned if the call fails. |
| MessageId | String | 889455942124347329 | The message ID that is generated by IoT Platform when the message is sent. |
| RequestId | String | BB71E443-4447-4024-A000-EDE09922891E | The request ID. |
| Success | Boolean | true | Indicates whether the call was successful. Valid values: - true - false |
Examples
Sample requests
https://si-d6e8d******958054/?Action=Pub
&ProductKey=a1Q5XoY****
&TopicFullName=/a1Q5XoY****/device1/user/get
&MessageContent=eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=
&Qos=0
&<Common request parameters>
Sample success responses
<PubResponse>
<RequestId>BB71E443-4447-4024-A000-EDE09922891E</RequestId>
<Success>true</Success>
<MessageId>889455942124347329</MessageId>
</PubResponse>
{
"RequestId":"BB71E443-4447-4024-A000-EDE09922891E",
"Success":true,
"MessageId":889455942124347329
}
