Use custom topics for communication - IoT Platform - Alibaba Cloud Documentation Center

A custom topic category covers the topics for all devices in a product. This topic describes how to define a custom topic category for a product and how to use custom topics for communication.

Background information

For information about how to define and use topics, see Topics.

Add a custom topic category

Log on to the IoT Platform console.
On the Overview page, click All environment. On the All environment tab, find the instance that you want to manage and click the instance ID or instance name.
In the left-side navigation pane, choose Devices > Products.
On the Products page, find the product for which you want to add a custom topic category and click View.
On the Product Details page, choose Topic Categories > Topic Category > Edit Topic Category.

In the Edit Topic Category dialog box, configure the parameters and click OK. The following table describes the parameters.

Parameter	Description
Device Operation Authorizations	The permission of the device on the topic category. Valid values: Publish, Subscribe, and Publish and Subscribe.
Topic Category	A topic category consists of several fields. Separate the fields with forward slashes (`/`). The name can contain letters, digits, and underscores (_). Each field of the topic category cannot be empty. If you use a cloud gateway product, no prefix is automatically specified. You must specify a custom value for the parameter. The value can contain wildcard characters, including plus signs (`+`) and number signs (`#`). You can use the `${deviceName}` variable to specify a DeviceName. If you use a non-cloud gateway product, take note of the following items: If you set the Device Operation Authorizations parameter of a topic category to Subscribe, you can specify the plus sign `+`) and number sign (`#`) wildcard characters in the topic category to allow devices to subscribe to multiple topics at the same time. `/${productKey}/${deviceName}/user/` is automatically specified as the prefix of the value of the parameter. You need to only specify a custom name for the topic category. Note For more information about how to use wildcard characters, see Custom topics with wildcard characters.
Enable Delegated Subscription	This parameter is available only if you set the Device Operation Authorizations parameter to Subscribe or Publish and Subscribe. If delegated subscription is enabled, IoT Platform assists devices in completing subscriptions when the devices of the product are connected to IoT Platform.
Enable Compression or Decompression	You can enable data compression and decompression for custom topics of Exclusive Enterprise Edition instances. For more information about this feature, see Data compression.
Description	The description of the topic category. You can configure this parameter to distinguish the features of different topic categories.

Manage topic categories

On the Topic Category tab, find a custom topic category. You can perform multiple operations on the topic category. The following table describes the operations.

Operation	Procedure
Modify a topic category	Click Edit in the Actions column. In the Edit Topic Category dialog box, modify the Device Operation Authorizations, Topic Category, and Description parameters. In the message that appears, click OK.
Delete a topic category	Warning After you delete a custom topic category, communication services that are related to the custom topic category become unavailable. This may interrupt your business. Proceed with caution. Click Delete in the Actions column. In the message that appears, click OK.
Specify whether to enable delegated subscription	Find a topic category whose Device Operation Authorizations parameter is set to Subscribe or Publish and Subscribe and turn off or turn on Enable Delegated Subscription.

Custom topics with wildcard characters

The following table describes the wildcard characters that you can use when you configure a custom topic category in the IoT Platform console.

Note

A topic that includes one or more wildcard characters represents a set of topics. If you grant the Publish or Subscribe permission on the topic and a device subscribes to the topic, you cannot use the topic to send messages.

On the Topic List tab of the device details page, the Publish Message action is not available for the topic. You cannot send messages to the device by using the topic.

Wildcard character

Description

This wildcard character must be specified for the last field in a topic and can match all field values at the current level and sub-levels.

For example, you create the /a1aycMA****/${deviceName}/user/# topic category. If Device 1 subscribes to the /a1aycMA****/device1/user/# topic, the device subscribes to all topics that start with /a1aycMA****/device1/user/, including /a1aycMA****/device1/user/update and /a1aycMA****/device1/user/update/error.

This wildcard character can match all field values at the current level.

For example, you create the /a1aycMA****/${deviceName}/user/+/error topic category. If Device 1 subscribes to the /a1aycMA****/device1/user/+/error topic, the device subscribes to multiple topics, such as /a1aycMA****/device1/user/get/error and /a1aycMA****/device1/user/update/error.

Communication based on custom topics

From IoT Platform to devices
IoT Platform calls the Pub API operation to publish messages to a topic. Devices receive messages from IoT Platform by subscribing to the topic.
From devices to IoT Platform
A device publishes messages to a custom topic. IoT Platform can receive messages from the device by using an Advanced Message Queuing Protocol (AMQP) server-side subscription or the data forwarding feature.

For more information about how to use custom topics, see Use custom topics for communication.