All Products
Search
Document Center

ApsaraMQ for MQTT:Quick start

Last Updated:Aug 07, 2024

This topic provides the quick start guide on how to use ApsaraMQ for MQTT to publish and subscribe to messages over the MQTT protocol that is supported by default.

If you want to access Message Queue for MQTT instances over a non-MQTT protocol, such as China New Energy Vehicle National Standards, you must purchase ApsaraMQ for MQTT Platinum Edition instances. Documentation and technical support services for Platinum Edition instances are provided in an exclusive channel.

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.

Figure 1. ProcessFlowchart

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

You must create the following resources:

  • ApsaraMQ for MQTT instance that is used to maintain client connections and forward messages

  • Message storage instance that is used to store messages. Only ApsaraMQ for RocketMQ instances are supported.

  • Parent topic that is a level-1 topic and used to publish and subscribe to messages.

  • Group ID that is used to identify a client.

  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 instanceSelect 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 instanceCreate 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 instanceCreate 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 IDCreate 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 endpointObtain an endpoint

ApsaraMQ for MQTT provides Public Endpoint and VPC Endpoint.

  • Public Endpoint is an IP address that is used to access ApsaraMQ for MQTT over the Internet. In most cases, public endpoints are used in the IoT and mobile Internet scenarios.

  • VPC Endpoint is an IP address that is used to access ApsaraMQ for MQTT in a private virtual cloud (VPC). In most cases, VPC endpoints are used by cloud applications to connect to ApsaraMQ for MQTT.

Important

If you want to use an endpoint to connect a client to ApsaraMQ for MQTT, use the domain name instead of the IP address because the IP address dynamically changes. The ApsaraMQ for MQTT technical team is not liable for faults and direct or indirect losses in the following scenarios:

  • You use an IP address to access your client to ApsaraMQ for MQTT. After the technical team of ApsaraMQ for MQTT updates the domain name resolution, the original IP address becomes invalid.

  • A firewall policy on IP addresses is set in the network in which your client is running. After the technical team of ApsaraMQ for MQTT updates the domain name resolution, new IP addresses are blocked due to the firewall policy.

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.

Note

ApsaraMQ for MQTT provides one-way SSL encryption, so the certificate does not need to be uploaded on the client. The server-side certificate is automatically issued with the request handshake and is strongly bound to the domain name of the endpoint. Therefore, custom certificate encryption is not supported.

Table 1. Ports

MQTT on TCP

SSL

WebSocket

WebSocket SSL/TLS

Flash

1883

8883

80

443

843

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 messagePublish 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 sentThe message has been sent.