ApsaraMQ for MQTT:MQTT quick start

Usage notes

ApsaraMQ for MQTT requires a backend message storage queue. Note the following points:

• An ApsaraMQ for MQTT instance is a stateless gateway. It maintains client connections and forwards messages for IoT and mobile scenarios. The instance itself does not provide message persistence; you must configure a separate storage instance to store messages.

• Each ApsaraMQ for MQTT instance (gateway instance) must be bound to a storage instance (an ApsaraMQ for RocketMQ instance).

• Currently, only ApsaraMQ for RocketMQ instances are supported as backend storage instances.

• You can create a limited number of ApsaraMQ for MQTT instances in the same region. Each ApsaraMQ for MQTT instance can be bound to only one corresponding ApsaraMQ for RocketMQ instance. For specific limits, see the information in the console.

When you use ApsaraMQ for MQTT, note the following network access restrictions:

A client can access a topic only if the client's group ID and the topic belong to the same instance and region. For example, if a topic is created in Instance A in the China (Beijing) region, it can be accessed only by ApsaraMQ for MQTT clients that use a group ID created in Instance A in the China (Beijing) region.

Workflow

The quick start workflow shows how to use ApsaraMQ for MQTT to send and receive messages.

As shown in the quick start workflow, you must create resources before you can use a client to send and receive messages. Otherwise, the ApsaraMQ for MQTT server rejects connections from clients with invalid client IDs.

Prerequisites

• You have activated ApsaraMQ for RocketMQ. If you have not activated the service, activate it.

• You have an Alibaba Cloud AccessKey. For more information, see Obtain an AccessKey.

Step 1: Create resources

1. Select a region.

   Select a region in which to create your resources based on your business requirements.

   1. Log on to the Message Queue for MQTT console.

   2. In the top navigation bar, select the region where you want to create your resources, for example, China (Beijing).

2. Create an ApsaraMQ for MQTT instance.

   Before you create an ApsaraMQ for MQTT instance, note the following:

   • The total number of instances of all types that you can create in each region is limited. For specific limits, see the information in the console.

   • Estimate the required transactions per second (TPS), number of connections, and number of subscriptions based on your business scenario to select appropriate instance specifications. For subscription instances, selecting specifications that are too low may trigger service throttling and affect your business.

   • Basic Edition instances take effect in real time after purchase. Platinum Edition instances require some time to deploy. You are notified when the instance is ready.

   Perform the following steps to create an ApsaraMQ for MQTT instance:

   1. In the left-side navigation pane, click Overview.

   2. On the Instances page, click Create Instance.

   3. On the buy page, select an edition and configure the specifications for your ApsaraMQ for MQTT instance as required. Then, complete the purchase as prompted.

   Return to the instance list on the Overview page in the console. You can view the ApsaraMQ for MQTT instance that you created.

3. Create and bind a data storage instance.

   After creating an ApsaraMQ for MQTT instance, you also need to create an instance to store topics and messages (currently, only ApsaraMQ for RocketMQ instances are supported), and then bind the created ApsaraMQ for RocketMQ instance to the ApsaraMQ for MQTT instance in a one-to-one relationship.

   This binding is subject to the following limits:

   • An ApsaraMQ for MQTT instance can be bound only once. After the binding is successful, it cannot be changed.

   • A storage instance can be bound to only one ApsaraMQ for MQTT instance. One-to-many binding is not supported.

   • The two instances to be bound must have the same namespace type. An instance with an exclusive namespace cannot be bound to an instance with a non-exclusive namespace.

   • If you prematurely delete the storage instance that is bound to an ApsaraMQ for MQTT instance, the ApsaraMQ for MQTT instance will become unavailable.

   Perform the following steps to create and bind a storage instance:

   1. In the left-side navigation pane, click Overview. Find the ApsaraMQ for MQTT instance that you created and click Continue to Configure.

   2. In the Message Persistence Settings dialog box, select an option based on your requirements.

      • If you have an ApsaraMQ for RocketMQ instance, select Select Existing Instance. A list of your existing message storage instances is displayed. Select the ApsaraMQ for RocketMQ message storage instance that you want to use and click Confirm to complete the binding.

      • If you do not have an ApsaraMQ for RocketMQ instance, select one of the following options:

        • Create Shared Instance: Creates a Standard Edition instance of ApsaraMQ for RocketMQ. Enter an instance name and description, and then click Confirm to create the instance.

        • Purchase Platinum Instance: Creates an ApsaraMQ for RocketMQ Platinum Edition instance. Select Purchase Platinum Instance and click Buy Now. Follow the on-screen instructions to complete the purchase.

        After you create the instance, repeat Step i and Step ii. Select Select Existing Instance, select the ApsaraMQ for RocketMQ instance that you just created, and then click Confirm to complete the binding.

4. Create a topic.

   To publish and subscribe to messages, you must first create a parent topic. You do not need to create subtopics in the console; they can be used directly in your code.

   A one-to-one binding is established between an ApsaraMQ for MQTT instance and its storage instance. Therefore, topics are created on the storage instance and a mapping relationship is created in the ApsaraMQ for MQTT console. All topic operations can be performed in the same way as those on the storage instance.

   If you have already created topics in ApsaraMQ for RocketMQ, you can use them directly. If not, perform the following steps to create a topic:

   1. In the left-side navigation pane, click Message Storage.

   2. On the Topic Management page, select the ApsaraMQ for MQTT instance that you created, and then click Create Topic.

   3. In the Create Topic dialog box, enter a name for the topic, select a message type, and add remarks. Then, click Confirm.

   Note

   If you need to send ordered messages from an ApsaraMQ for MQTT client, you must use an ordered topic. However, ApsaraMQ for MQTT clients do not support strictly ordered message consumption.

5. Create a group ID.

   In ApsaraMQ for MQTT, a group ID identifies a group of clients with an identical logical function, such as a class of similar devices. The group ID and a device ID form the client ID that identifies an MQTT client. For more information, see Terms.

   1. In the left-side navigation pane, click Group Management.

   2. On the Group Management page, select the ApsaraMQ for MQTT instance that you created and click Create Group ID.

   3. In the Create Group ID dialog box, enter the group ID that you want to create and click OK.

   After the group ID is created, it appears on the Group Management page. This page displays all group IDs that you own in the current region.

   Note

   • If a group ID is no longer in use, delete it promptly.

   • A group ID can only be used by the account that created it. For example, a RAM user cannot use a group ID created by the parent Alibaba Cloud account and must create their own.

Step 2: Obtain an endpoint

When you use an SDK to send and receive messages, you must specify the endpoint of the ApsaraMQ for MQTT instance. An endpoint consists of a domain name and a port number.

After the ApsaraMQ for MQTT instance is bound to the ApsaraMQ for RocketMQ instance, the endpoint information is displayed in the Endpoint Information section. You can obtain the endpoint information from this section.

After the ApsaraMQ for MQTT instance and the ApsaraMQ for RocketMQ instance are bound, you can also perform the following steps to obtain the endpoint:

1. In the top navigation bar of the console, select the region where you created the resources. Then, in the left-side navigation pane, click Instance Details.

2. On the Instance Details page, select the ApsaraMQ for MQTT instance that you created and click the Instance Information tab.

3. On the Instance Information tab, find the Endpoint Information section to view the required endpoint domain name. In this section, find the public endpoint field and click Copy to get the endpoint address.

Port

In addition to the standard MQTT on TCP protocol, ApsaraMQ for MQTT supports MQTT over SSL, WebSocket, WebSocket over SSL/TLS, and Flash. The corresponding service ports are listed in Port descriptions. Select a port based on your requirements.

Step 3: Publish and subscribe to messages

1. Download a client SDK. For the download links for SDKs in different languages, see SDK Downloads.

   Because ApsaraMQ for MQTT supports the standard MQTT protocol by default, we recommend that you use open-source third-party client SDKs. If an SDK for your programming language is not provided, you can search for other MQTT-compatible SDKs.

2. Download a demo project to view parameter descriptions. You can then run the demo to publish and subscribe to messages. For demo download links, see Demo Projects.

   The demo library supports several common programming languages and will be expanded over time. Demos showcase basic features and you must modify their parameters for your application and production environment.

More information

You can also send a message from the console to quickly verify a topic's availability. To do this, perform the following steps:

1. In the left-side navigation pane, click Message Storage.

2. On the Message Storage page, in the Topic List section, find the topic that you created, and click Send in the Actions column.

3. In the Send Message dialog box, set the message properties, enter the message content, and then click OK.

   The console returns a success notification and the corresponding message ID.