ApsaraMQ for MQTT：Quick start

Precautions

ApsaraMQ for MQTT must be used with backend message storage queues. Take note of the following points:

• A ApsaraMQ for MQTT instance is a stateless gateway instance that is used to maintain client connections and to forward messages in mobile Internet and IoT scenarios. The Message Queue for MQTT instance does not support message data persistence. Therefore, you must configure a message storage instance to store messages and support message data persistence.

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

• Currently, only a ApsaraMQ for RocketMQ backend storage instance can be used as a message storage instance.

• A limited number of ApsaraMQ for MQTT instances can be created in the same region. A ApsaraMQ for MQTT instance can be bound to only one ApsaraMQ for RocketMQ instance. For the maximum number of instances that can be created in one region, see the prompts in the console.

Before you use ApsaraMQ for MQTT, take note of the following network access limits:

Only the topics and group IDs on the same instance in the same region can be interconnected. For example, if a topic is created on Instance A in the China (Beijing) region , the topic can be accessed only by the ApsaraMQ for MQTT client (hereinafter referred to as the client) with the group ID that is created on Instance A in the China (Beijing) region.

Procedure

Process shows how to use ApsaraMQ for MQTT to publish and subscribe to messages.

You must create resources before you publish and subscribe to messages on clients, as shown in the Process. Otherwise, the ApsaraMQ for MQTT broker denies invalid connections to the clients.

Prerequisites

• ApsaraMQ for RocketMQ has been activated. If Message Queue for Apache RocketMQ is not activated, activate this service.

• An Alibaba Cloud AccessKey pair has been obtained. For more information, see Obtain an AccessKey pair.

Step 1: Create resources

1. Select a region.

   Select a region in which you want to create resources based on your business needs.

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

   2. In the top navigation bar, select a region in which you want to create resources, such as China (Beijing).

2. Creates a ApsaraMQ for MQTT instance.

   First, you must create a ApsaraMQ for MQTT instance. Take note of the following points before you create the instance:

   • A limited number of instances of all types can be created in each region. For information about the specific limits, see the prompts in the console.

   • Estimate the transactions per second (TPS), the number of connections, and the number of subscriptions based on the business scenario. Select appropriate instance specifications. For subscription instances, if you select an excessively small specification, service throttling may be triggered and your services may be affected.

   • A Basic Edition instance takes effect upon purchase. It takes some time to deploy a Platinum Edition instance after the instance is purchased. You will be notified when the instance is available.

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

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

   2. On the Instances page, click Create Instance.

   3. On the page that appears, select a ApsaraMQ for MQTT instance type and specify configurations as needed. Follow the on-screen instructions to complete the purchase.

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

3. Create and bind a storage instance.

   After you create a ApsaraMQ for MQTT instance, you also need to create an instance to store topics and messages. Currently, you can create only a ApsaraMQ for RocketMQ instance to store topics and messages. Then, bind the ApsaraMQ for RocketMQ instance to the ApsaraMQ for MQTT instance.

   Take note of the following limits when you bind the instances:

   • A ApsaraMQ for MQTT instance can be bound only once, and its bound message storage instance cannot be changed once the binding is complete.

   • Each storage instance can be bound to only one ApsaraMQ for MQTT instance. One-to-multiple 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 delete the storage instance that is bound to an ApsaraMQ for MQTT instance, the ApsaraMQ for MQTT instance may be unavailable.

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

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

   2. In the Message Persistence Settings dialog box, set the parameters based on the instance situation and your requirements.

      • If you have purchased a ApsaraMQ for RocketMQ instance, select Select Existing Instance. After you select this option, a list of message storage instances that you have created or purchased is displayed. Click your existing ApsaraMQ for RocketMQ instance that is used as the message storage instance, and then click Confirm to complete the binding.

        Figure 2. Select an existing instance

      • If you have not purchased a ApsaraMQ for RocketMQ instance, select the following option:

        • Create Shared Instance: You need to create a ApsaraMQ for RocketMQ Standard Edition instance. Enter an instance name and description. Then, click OK.

          Figure 3. Create a shared instance

        • Purchase Platinum Instance: You need to create a ApsaraMQ for RocketMQ Platinum Edition instance. Select Purchase Platinum Instance, and click Buy Now. Follow the on-screen instructions to purchase or create the instance.

          Figure 4. Create a Platinum Edition instance

        After the instance is created, repeat steps i and ii and select Select Existing Instance. Click the ApsaraMQ for RocketMQ instance that you created, and then click OK to complete the binding.

4. Create a topic.

   To publish and subscribe to messages over MQTT, you must create an MQTT parent topic. Subtopics at different levels can be directly added in code without the need to create them in the console.

   A one-to-one binding relationship is established between the ApsaraMQ for MQTT instance and the storage instance. Therefore, the topic is actually created on the storage instance and mapped to the ApsaraMQ for MQTT console. You can also perform all topic operations in the Message Queue for Apache RocketMQ console.

   If you have created a topic when you use ApsaraMQ for RocketMQ, you can also use the topic directly. If you have not created a topic, perform the following steps to create a topic:

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

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

   3. In the Create Topic dialog box, enter a topic name, select the type of messages to be stored, published, and subscribed to for the topic, and enter remarks. Then, click OK.

   Note

   To use a ApsaraMQ for MQTT client to publish ordered messages, select the ordered message type. Currently, ApsaraMQ for MQTT clients do not support strongly ordered messages in consumption scenarios.

5. Create a group ID.

   In ApsaraMQ for MQTT, a group ID specifies a group of nodes with identical logic and features. A group ID represents a set of devices that have the same features. A group ID and a device ID are used together to identify the client ID of a Message Queue for MQTT client. For more information, see Terms.

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

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

      Figure 5. Create a group ID

   3. In the Create Group ID dialog box, enter a group ID and click OK.

   After the group ID is created, the new group ID appears on the Groups page. The Groups page shows all your group IDs in the current region.

   Note

   • Delete a group ID at the earliest opportunity if you no longer use it.

   • A group ID can only be used by the account that created it. A group ID that is created by an Alibaba Cloud account cannot be used by Resource Access Management (RAM) users in the Alibaba Cloud account. RAM users must create their own group IDs separately.

Step 2: Obtain an endpoint

To use an SDK to publish and subscribe to messages, you must specify an endpoint of the ApsaraMQ for MQTT instance in the SDK. The endpoint of a ApsaraMQ for MQTT instance consists of the domain name of the endpoint and the port.

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

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

1. In the top navigation bar of the console, select the region where the created resource is located, and then click Instances in the left-side navigation pane.

2. On the Instances page that appears by default, select the created ApsaraMQ for MQTT instance and click the Instance Information tab.

3. On the Instance Information tab page, view the domain name of the endpoint in the Endpoint Information section.

   Figure 6. Obtain an endpoint

Ports

Currently, ApsaraMQ for MQTT supports MQTT on TCP, MQTT SSL, WebSocket, WebSocket SSL/TLS, and Flash. The corresponding service ports are listed in Ports. Replace the port number in an endpoint as required.

Step 3: Publish and subscribe to messages by using an SDK

1. Download the client SDK. For information about the download addresses of SDKs in different languages, see Download the SDK.

   ApsaraMQ for MQTT supports the standard MQTT protocol by default, so we recommend that you use open source third-party client SDKs. If a client SDK in a desired language is not listed, search for MQTT-compatible SDKs on the Internet.

2. Download the demo project, view the corresponding parameter descriptions, and then you can run the demo to publish and subscribe to messages. For information about the download address of the demo, see Demo projects.

   The current demo library only covers some mainstream languages and will be updated later. If the corresponding development language is not covered, download a Java demo for modification. The demo project only shows you basic functions. You must modify all parameters based on your application and production environment.

Additional information

In addition to publishing messages by using an SDK or API, you can also publish messages in the console to quickly verify the availability of the topic by performing the following steps:

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

2. In the Topics section on the Message Storage page, find the topic that you created and click Send in the Actions column.

   Figure 7. Publish a message

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

   The console returns a notification that the message has been sent and the corresponding message ID.

   Figure 8. Message sent