Pub - IoT Platform

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. If you want to subscribe to the broadcast messages of a custom topic for more than 1,000 devices, you can use Message Queuing Telemetry Transport (MQTT) 5.0 for communication, enable the broadcasting feature for the custom topic, and then specify the messages of the custom topic as retained messages. For more information, see UpdateTopicConfig.

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.

QPS limits

You can call this API operation up to 1,600 times per second per account.

Note

The Resource Access Management (RAM) users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

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. For more information, see Topics. 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.
IotInstanceId	String	No	iot-cn-0pp1n8t****	The ID of the instance. You can view the ID of the instance on the Overview page in the IoT Platform console. Important If your instance has an ID, you must specify the ID for this parameter. Otherwise, the call fails. If the Overview page is not displayed or if your instance does not have an ID, you do not need to specify this parameter. For more information, see the Overview topic of IoT instances.
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. For more information about messaging, see the "Device connection" section in the Limits topic.
ResponseTopic	String	No	/a1Q5XoY****/device1/user/update	The response topic in request/response communication mode when you use MQTT 5.0 for communication. For more information, see MQTT 5.0.
CorrelationData	String	No	aGVsbG8****	The related data in request/response communication mode when you use MQTT 5.0. You can configure this parameter based on your business requirements. A message recipient can process the request based on the data. Note You must convert the related data into binary data and perform Base64 encoding to generate a value of the string type.
UserProp.N.Key	String	No	key1	The custom property key that is specified when you use MQTT 5.0 for communication. You must use this parameter together with the UserProp.N.Value parameter.
UserProp.N.Value	String	No	value1	The custom property value that is specified when you use MQTT 5.0 for communication. You must use this parameter together with UserProp.N.Key.
DeviceName	String	No	device1	The name of the MQTT cloud gateway. Important This parameter is required only if you want to send a message to an MQTT cloud gateway.
ContentType	String	No	text	The content type of the message when you use MQTT 5.0 for communication. This parameter specifies the type of an MIME file, such as text or plain.
PayloadFormatIndicator	Integer	No	1	The payload identifier of the message when you use MQTT 5.0 for communication. Valid values: 0: The message is unknown byte data. 1: The payload of the message is character data that is encoded in UTF-8.
Retained	Boolean	No	true	Specifies whether to label the message as a retained message when you use MQTT 5.0 for communication. true false
MessageExpiryInterval	Long	No	2	The validity period of the message when you use MQTT 5.0 for communication. Unit: seconds. The validity period of QoS 0 messages ranges from 0 to 86,400 seconds. The validity period of QoS 1 messages ranges from 0 to 604,800 seconds.
TopicAlias	Integer	No	123	The topic alias that you can specify when you use MQTT 5.0 for communication. The topic alias helps reduce the communication traffic between devices and IoT Platform. Important Topic aliases work based on mappings between topic names and aliases. Devices and IoT Platform must maintain the corresponding mappings. A mapping is created the first time a device uses an alias to send messages and is deleted when the device is disconnected. A mapping is created between a topic name and an alias each time a device reconnects to IoT Platform and uses the corresponding topic to send messages. Each alias must be unique. An alias corresponds to only one topic name. If you use a topic alias, do not concurrently publish messages. Otherwise, messages that are concurrently published may be lost due to the distributed architecture of IoT Platform. If you use a topic alias, you must specify TopicAlias every time you call the Pub operation. IoT Platform supports up to 20 topic aliases. This indicates that the downstream messages of a device can use up to 20 topic aliases. For more information about topic aliases, see Topic aliases in MQTT 5.0 features.

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://iot.cn-shanghai.aliyuncs.com/?Action=Pub
&ProductKey=a1Q5XoY****
&TopicFullName=/a1Q5XoY****/device1/user/get
&MessageContent=eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=
&Qos=0
&ResponseTopic=/a1Q5XoY****/device1/user/update
&CorrelationData=aGVsbG8%3D****
&UserProp.1.Key=k1&UserProp.1.Value=v1
&<Common request parameters>

Sample success responses

XML format

<PubResponse>
    <RequestId>BB71E443-4447-4024-A000-EDE09922891E</RequestId>
    <Success>true</Success>
    <MessageId>889455942124347329</MessageId>
</PubResponse>

JSON format

{
      "RequestId":"BB71E443-4447-4024-A000-EDE09922891E",
      "Success":true,
      "MessageId":889455942124347329
  }

Error codes

For a list of error codes, see Service error codes.