All Products
Search

This Product

    IoT Platform:Pub

    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.