UpdateTopicConfig - IoT Platform - Alibaba Cloud Documentation Center

Usage notes

You can subscribe to the broadcast messages of a custom 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.

Perform the following steps:

1.Call the UpdateTopicConfig operation and set the EnableBroadcast parameter to true to allow a custom topic to broadcast messages. In this example, the /broadcast/a1Q5XoY****/test custom topic is used.

2. Call the Pub operation to broadcast messages to the /broadcast/a1Q5XoY****/test topic and set the Retained parameter to true to specify the messages as retained messages.

3. Call the SubscribeTopic operation to subscribe to the /broadcast/a1Q5XoY****/test topic for a device. This way, the device can receive the retained messages from the custom topic.

QPS limits

You can call this operation up to 100 times per second per account.

Note The 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	UpdateTopicConfig	The operation that you want to perform. Set the value to UpdateTopicConfig.
ProductKey	String	Yes	a1Q5XoY****	The ProductKey of the product to which the device belongs.
TopicFullName	String	Yes	/broadcast/a1Q5XoY****/test	The name of the custom topic. If you use an MQTT cloud 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 cloud gateway device, specify the custom topic in the `/broadcast/${productKey}/${custom field}` format or the `/${productKey}/${deviceName}/user/${custom field}` format. If you want to use the custom topic to broadcast messages, specify the custom topic in the /broadcast/${productKey}/${custom field} format. The value of the `${productKey}` variable is the same as the value of the ProductKey parameter. The `${custom field}` variable specifies a custom field. Important If you want to use a custom topic 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. Devices for which you want to subscribe to the topic must have the Subscribe or Publish and Subscribe permission on the topic.
IotInstanceId	String	No	iot-0pp1n8t****	The ID of the instance. You can view the ID of the instance on the Overview tab 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 your instance does not have an ID, you do not need to configure the parameter. For more information, see Overview.
EnableBroadcast	Boolean	No	true	Specifies whether to enable the broadcasting feature. Valid values: true: enables the broadcasting feature. false: disables the broadcasting feature.
Operation	String	No	SUB	The permissions that you want to grant to the device on the topic category. Valid values: SUB: subscribe PUB: publish ALL: publish and subscribe
EnableProxySubscribe	Boolean	No	false	If you set the Operation parameter to SUB or ALL, you can enable the delegated subscription feature. Valid values: true: enables the delegated subscription feature. false: disables the delegated subscription feature. If you enable the delegated subscription feature for a topic, IoT Platform obtains the details of the topic and helps a device subscribe to the topic when you connect the device to IoT Platform.
Codec	String	No	compress	Specifies whether to enable the data compression or decompression feature for a custom topic. This parameter is available only if you use a Standard or Exclusive Enterprise Edition instance. Valid values: compress: enables data compression. decompress: enables data decompression. For more information, see Data compression.
Description	String	No	submit a test topic	The description of the topic. The description must be 1 to 100 characters in length.

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 returned if the call fails. For more information, see the "Error codes" section of this topic.
Message	String	A system exception occurred.	The error message returned if the call fails.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	The ID of the request.
Success	Boolean	true	Indicates whether the call was successful. Valid values: true: The call was successful. false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=UpdateTopicConfig
&EnableBroadcast=true
&ProductKey=a1Q5XoY****
&TopicFullName=/broadcast/a1Q5XoY****/test
&IotInstanceId=iot-0pp1n8t****
&<Common request parameters>

Sample success response

XML format

<RequestId>E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565</RequestId>
<Code/>
<Success>true</Success>

JSON format

{
    "RequestId": "E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565",
    "Code": "",
    "Success": true
}

Error codes

HttpCode	Error Code	Error message	Description
400	iot.message.broker.ParamCheckError	Param check error.	The system failed to verify the value of the parameter.
400	iot.message.broker.ProductCheckError	Product check error.	The system failed to authenticate the product.
400	iot.message.broker.TopicConfigNumExceed	Topic config num exceed.	The number of topics that you specified exceeds the limit.
400	iot.message.broker.SystemError	System error.	A system exception occurred.
400	iot.messagebroker.InvalidPubTopicFormat	The pub topic cannot contain wildcard characters.	The name of the topic to which you want to send messages cannot contain wildcard characters.
400	iot.messagebroker.InvalidOperationWithBroadcast	The operation must be sub for enabling broadcast.	The device can perform only the Subscribe operation on the topic for which the broadcasting feature is enabled.
400	iot.messagebroker.InvalidTopicWithBroadcast	Topics for which broadcast is enabled cannot contain wildcard characters.	The name of a topic for which the broadcasting feature is enabled cannot contain wildcard characters.
400	iot.messagebroker.InvalidOperationWithProxySubscribe	The operation must be sub or all for enabling proxy subscription.	The device can perform only the Subscribe or All operation on the topic for which the delegated subscription feature is enabled.
400	iot.messagebroker.InvalidTopicWithProxySubscribe	Topics for which proxy subscription is enabled cannot contain wildcard characters.	The name of the topic for which the delegated subscription feature is enabled cannot contain wildcard characters.
400	iot.messagebroker.InvalidTopicWithCodec	Topics for which compression and decompression are enabled cannot contain wildcard characters.	The name of the topic for which the compression or decompression feature is enabled cannot contain wildcard characters.
400	iot.messagebroker.InvalidInstanceWithCodec	Only Exclusive Enterprise Edition instances support compression and decompression.	Only Exclusive Enterprise Edition instances support the data compression or decompression feature.
400	iot.prod.NotExistedProduct	The specified product does not exist.	The product that you specified does not exist.

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