All Products
Search
Document Center

IoT Platform:Pub

Last Updated:Sep 05, 2023

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.

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.