edit-icon download-icon

Quick start guide

Last Updated: Oct 19, 2018

This topic describes the complete process from activating the MQ service and creating the MQ resources, to sending and receiving messages using the MQ SDK, aiming at getting you started with MQ in the simplest and quickest way.

To demonstrate how to send and subscribe to messages, this topic uses MQ’s Java SDK and the TCP protocol as the example.

Quick Start Flowchart

quickstart_process

Step 1: Activate MQ service

To activate the MQ service, follow the steps below:

  1. Log on to the Alibaba Cloud website, move the cursor to Products > Middleware, and click Message Queue to enter the MQ homepage.
  2. On the MQ homepage,click Buy Now to enter the MQ service activation page, and complete the activation according to the prompts.

If you have already activated the MQ service, log on to the MQ console directly.

Step 2: Create resources

In the MQ system, a producer sends messages to a specified Topic, and a consumer obtains and consumes messages after subscribed to the that Topic.

For your applications to access MQ, you need to create related MQ resources first, including:

Note: Once you have deleted the resources, such as the Topics, the producer IDs and the consumer IDs, their related resources will also be cleared within 10 minutes.

Create a Topic

Topic is the primary classification of messages in MQ, for example, you can create a Topic named “Topic_Trade” for the trade related messages. The first step of using MQ is to create Topics for your application.

You can create a Topic by following the steps below:

  1. Log on to MQ Console to enter the Topics page by default.

  2. Select a region (such as Internet region), and then click Create Topic.

    Note:

    • For testing purposes or local (non-Alibaba Cloud ECS instance ) usage of the MQ service, please create your Topics in the internet environment. The producers and the consumers can be deployed locally or deployed on an ECS instance in any region on the premise that the local servers or the corresponding ECS instances can access the internet.
    • To use the MQ service in a production environment, you must deploy your application on an ECS instance, and create the Topics in the region where the application is located, that is the region where the corresponding ECS instance is located.
    • A Topic cannot be used cross regions. For example, if a Topic is created in “North China 2,”, both the message producer and consumer must also be running on an ECS instance in “North China 2.”
    • For detailed information about regions, see Regions and Zones in the ECS documentation.
  3. In the Create Topic dialog box, enter a Topic name and a remark, and click OK, and the topic you just created will appear in the Topic list.

    Note: The Topic name must be globally unique. If a name is already used by another user, you are not able to create a Topic with that name any more.

Message type

There are the following several types of messages:

  • Unordered messages: The First-In-First-Out (FIFO) order is not guaranteed; include normal messages, scheduled/delayed messages and transactional messages. We recommend that you create different Topics to send different types of messages, for example, to create Topic A for normal messages, Topic B for transactional messages, and Topic C for scheduled/delayed messages.
  • Globally ordered massage: All messages are produced and consumed in strict FIFO order.
  • Partitionally ordered messages: Messages are partitioned by sharding keys, so as to improve overall concurrency and performance. Messages in the same partition are produced and consumed in strict FIFO order.

Create a Producer ID

Once you have created a Topic, you then need to create the resource for message production for the Topic, that is, to create a Producer ID. One Topic can only correspond to one Producer ID.

To create a Producer ID for your Topic, follow the steps below:

  1. On the left-side navigation pane in the MQ console, Select Topics.

  2. On the Topics page, locate the Topic you just created, and click Create Producer in the Actions column.

  3. On the Create Producer page, enter a Producer ID, and click OK.

    Note:

    • The Producer ID must be globally unique. If a name already exists, you are not able to create a Producer ID with that name any more.
    • A Topic and its producer must be located in the same region, for example, if you have created “Topic_open” in the “Internet,” region, then the Producer ID for “Topic_open” must also be located in the “Internet” region.
    • The relationship between Producer ID and Topic is 1:N; that is, one Topic can only be bound with one Producer ID, while one Producer ID can be bound with multiple topics.

Create a Consumer ID

Once you have created the message producer, you need to create the resource for message consumption for the Topic, that is, to create Consumer IDs.

To create a Consumer ID, follow the steps below:

  1. On the left-side navigation pane in the MQ console, Select Topics.

  2. On the Topics page, locate the Topic you just created, and click Create Consumer in the Actions column.

  3. On the Create Consumer page, and click OK.

    Note:

    • The Consumer ID must be globally unique. If a name already exists, you are not able to create a Consumer ID with that name any more.
    • A Consumer ID and its corresponding Topic must located in the same region, for example, “Topic_open” in the “Internet” region can be bound with the Consumer ID “CID_123,” which is also located in the “Internet” region, but “Topic_huabei1” in the “North China 1” region cannot be bound with this Consumer ID.
    • The relationship between Consumer ID and Topic is N:N. One Consumer ID can subscribe to multiple Topics, and one Topic can correspond to multiple Consumer IDs.

Create Alibaba Cloud AccessKey and SecretKey

When using SDK/API to send and subscribe to messages, you not only need to specify the Topic, Producer ID, and consumer ID, but also need to enter your identity verification information that you have created in the RAM console, that is, the Access Key ID and Access Key Secret.

Please refer to Create AccessKey on how to create AccessKey and SecrectKey.

Once the above preparation is done, you can run sample code and use MQ to send and subscribe to messages.

Step 3: Obtain Endpoint

After creating resources in console, you should obtain the TCP endpoints of Producer ID and Consumer ID.

To obtain the endpoint of Producer ID or Consumer ID, take the following steps:

  1. On the left-side navigation pane in the MQ console, choose Producers or Consumers.

  2. On the right side of the target Producer ID or Consumer ID, click Endpoint in Actions list.

  3. In Endpoint dialogue box, click Copy.

Once the above preparation is done, you can run sample code and use MQ to send and subscribe to messages.

Step 4: Send messages

You can send messages via the console or SDK/API.

  • To quickly verify the availability of the Topics, you can send messages via the console.

  • In a production scenario, we recommend that you use SDK/API for message sending.

Send messages via the console

To send messages via the console, follow the steps below:

  1. Click Producers in the left-side navigation pane of the MQ console.

  2. Locate the Topic you just created in the list, and in the Actions column, click Send.

  3. In the Send Message dialog box, enter the message content, and click OK. The console will return a confirmation message and the corresponding message ID once the message is sent successfully.

Send messages via SDK/API

In a production scenario, it is suggested that you use SDK/API to send messages. This section demonstrates to you how to do it by using the Java SDK under the TCP protocol. If you want to use other protocols or development languages, see the related help documentation.

Send messages via TCP Java SDK

  1. Dependency can be introduced through either one of the following two methods:

    • Introduce dependency using Maven:

      1. <dependency>
      2. <groupId>com.aliyun.openservices</groupId>
      3. <artifactId>ons-client</artifactId>
      4. <version>"XXX"</version>
      5. //version number of the latest Java SDK
      6. </dependency>

      About the version number of the latest Java SDK, see Release notes.

    • Download a dependency JAR package:

      About the download link of the latest Java SDK, see Release notes.

  2. Set related parameters and run sample code according to the following instructions:

    Note: For TCP endpoint, enter Producers page in MQ console, and on the right side of the target PID, click Endpoint in Actions list.

    1. import com.aliyun.openservices.ons.api.Message;
    2. import com.aliyun.openservices.ons.api.Producer;
    3. import com.aliyun.openservices.ons.api.SendResult;
    4. import com.aliyun.openservices.ons.api.ONSFactory;
    5. import com.aliyun.openservices.ons.api.PropertyKeyConst;
    6. import java.util.Properties;
    7. public class ProducerTest {
    8. public static void main(String[] args) {
    9. Properties properties = new Properties();
    10. // The producer ID you have created on the MQ console
    11. properties.put(PropertyKeyConst.ProducerId, "XXX");
    12. // Authentication AccessKey which has been created on Alibaba ECS Management Console
    13. properties.put(PropertyKeyConst.AccessKey,"XXX");
    14. // Authentication SecretKey which has been created on Alibaba ECS Management Console
    15. properties.put(PropertyKeyConst.SecretKey, "XXX");
    16. // Set the TCP endpoint, enter Producers page in MQ console, and on the right side of the target PID, click Endpoint in Actions list.
    17. // Internet region of public cloud here
    18. properties.put(PropertyKeyConst.ONSAddr,
    19. "http://onsaddr-internet.aliyun.com/rocketmq/nsaddr4client-internet");
    20. Producer producer = ONSFactory.createProducer(properties);
    21. // A start method must be called once before message sending to start a producer
    22. producer.start();
    23. //Send messages recurrently
    24. while(true){
    25. Message msg = new Message( //
    26. // The Topic which has been created on the console, i.e., a Topic name of the message
    27. "TopicTestMQ",
    28. // Message Tag,
    29. // It can be understood as a Tag in Gmail used for reclassifying the message so as to facilitate the consumer to specify a filter condition to implement a filter in the MQ broker
    30. "TagA",
    31. // Message Body
    32. // It may be any data in binary form, and MQ will make no intervention
    33. // Compatible serialization and deserialization methods that need to be negotiated by the producer and the consumer
    34. "Hello MQ".getBytes());
    35. // Set a critical service property representing the message, and try to keep the critical service property globally unique, such that you can query and resend the message via the MQ console when you cannot receive the message normally
    36. // Note: No setting will affect the normal sending and receiving of messages
    37. msg.setKey("ORDERID_100");
    38. // Message sending will succeed as long as an exception is not thrown
    39. // Print the message ID to facilitate querying the message sending status
    40. SendResult sendResult = producer.send(msg);
    41. System.out.println("Send Message success. Message ID is: " + sendResult.getMessageId());
    42. }
    43. // The producer object can be destroyed before exiting the application
    44. // Note: it's OK if the producer object has not been destroyed
    45. producer.shutdown();
    46. }
    47. }

Check whether a message is successfully sent

Once a message is sent, you can check its sending status in the console by following the steps below:

  1. On the left-side navigation pane of the MQ console, choose Message Query.

  2. On the Message Query page, select the By Message ID tab.

  3. In the search box, enter the message ID returned after the message is sent, and click Search to query the sending status of the message.

    “Storage time” indicates the time period for which the MQ server stored the message. when the MQ broker stores the message. If the message can be queried out, it means that the message has been successfully sent to the server.

Note: This section demonstrates the scenario where MQ is first used, when the consumer has not been started yet. Therefore, the message status shows that there is not any consumption data available. To start the consumer and subscribe to messages, see Step 4: Subscribe to messages. For more information on the message status, see Message Query.

Step 5: Subscribe to messages

Once a message is successfully sent, the subscription party needs to be started for message subscription. This topic introduces how to complete message subscription by calling related protocols and development languages by taking TCP Java SDK as an example.

Subscribe to messages by calling TCP Java SDK

You can run the following sample code to start the subscription end and test the function of subscribing messages. Related parameters should be correctly set according to the instructions. Currently, the console provides sample codes of Java, C++, and .NET.

Note: For TCP endpoint, enter Consumers page in MQ console, and on the right side of the target CID, click Endpoint in Actions list.

  1. import com.aliyun.openservices.ons.api.Action;
  2. import com.aliyun.openservices.ons.api.ConsumeContext;
  3. import com.aliyun.openservices.ons.api.Consumer;
  4. import com.aliyun.openservices.ons.api.Message;
  5. import com.aliyun.openservices.ons.api.MessageListener;
  6. import com.aliyun.openservices.ons.api.ONSFactory;
  7. import com.aliyun.openservices.ons.api.PropertyKeyConst;
  8. import java.util.Properties;
  9. public class ConsumerTest {
  10. public static void main(String[] args) {
  11. Properties properties = new Properties();
  12. // The consumer ID you have created on the MQ console
  13. properties.put(PropertyKeyConst.ConsumerId, "XXX");
  14. // Authentication AccessKey which has been created on Alibaba ECS Management Console
  15. properties.put(PropertyKeyConst.AccessKey, "XXX");
  16. // Authentication SecretKey which has been created on Alibaba ECS Management Console
  17. properties.put(PropertyKeyConst.SecretKey, "XXX");
  18. // Set the TCP endpoint, enter Consumers page in MQ console, and on the right side of the target CID, click Endpoint in Actions list.
  19. // Internet region of public cloud here
  20. properties.put(PropertyKeyConst.ONSAddr,
  21. "http://onsaddr-internet.aliyun.com/rocketmq/nsaddr4client-internet");
  22. Consumer consumer = ONSFactory.createConsumer(properties);
  23. consumer.subscribe("TopicTestMQ", "*", new MessageListener() {
  24. public Action consume(Message message, ConsumeContext context) {
  25. System.out.println("Receive: " + message);
  26. return Action.CommitMessage;
  27. }
  28. });
  29. consumer.start();
  30. System.out.println("Consumer Started");
  31. }
  32. }

Check whether messages are successfully subscribed to

Once said steps have been completed, you can check whether the subscription end has been successfully started on the MQ console, i.e., whether a message is successfully subscribed to.

  1. Click Consumers in the left-side navigation pane of the MQ console.

  2. Locate the Topic to be checked, and click Consumer Status in the right action options.
    If Online is displayed as Yes, it means that the subscription end has been successfully started. If the consumer status Online is displayed as No, it means that the consumption end has not been started or has failed to start.

When all the steps are completed, you can succeed in accessing the MQ service, and use MQ for message sending and receiving.

Thank you! We've received your feedback.