All Products
Search
Document Center

Quick start for primary accounts

Last Updated: Sep 13, 2019

This topic describes the complete process, from activating the MQ service and creating the MQ resources to sending and receiving messages using the SDK from the primary account perspective, helping you get started with MQ in the simplest and quickest way.

Step 1: Activate the MQ service

To activate the MQ service, follow the steps below:

  1. Log on to the Alibaba Cloud website. Choose Products > Middleware > Message Queue. Then click MQ.

  2. On the MQ homepage, click Buy Now to enter the MQ activation page, and activate the service as prompted.

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

Step 2: Create resources

Resource types

When a new application accesses MQ, you need to create the following MQ resources for the application:

  • Instance: As a VM resource of MQ, the instance stores the topics and group IDs of messages.

  • Topic: In the message system of MQ, the producer sends a message to a specified topic and the consumer subscribes to the topic to obtain and consume the message.

  • Group ID: It is used to identify the consumer or producer of the message.

  • Alibaba Cloud AccessKey: is used to authenticate the account to send or receive messages.

Note: When an instance is deleted, all topics and group IDs of the instance are cleared within 10 minutes. When a single topic or group ID is deleted, other resources are not affected.

Network access

Network access of MQ is constrained as follows:

  • A topic can be accessed only by a producer or consumer corresponding to the group on the same instance in the same region as the topic.

    For example, when a topic is created in Instance A in the region China North 2 (Beijing), the topic can be accessed only by the producer and consumer corresponding to the group ID created in Instance A in the region China North 2 (Beijing).

  • If you want to perform a test or use MQ on a local server (other than an Alibaba Cloud ECS instance), you can create both the topic and group ID in an instance in the region Internet. Producers and consumers can be deployed on a local server or an ECS instance in any region, provided that the local server or ECS instance can access the Internet. However, a topic created in one instance cannot be accessed from another instance.

For more information about regions, see Regions and zones in the ECS documentation.

Select a region

  1. Log on to the MQ console.

  2. Select a region, for example, Internet, in which you want to create a resource.

Note: Currently, HTTP-based instances can only be deployed in the region China East 1 (Hangzhou).

Create instances

  1. In the left-side navigation pane, choose Instances.

  2. On the Instances page, click Create Instance.

  3. In the Create Instance dialog box, select the instance type, enter a name and description for the instance, and click OK.

Create topics

Topic is the first-level identifier for classifying messages in MQ. For example, you can create a topic named Topic_Trade for transaction messages.

  1. In the left-side navigation pane, choose Topics.

  2. On the Topics page, select the instance you created.

  3. Click Create Topic.

  4. In the Create Topic dialog box, enter a name for the topic in the Topic field.

Note: The topic name must be unique in the same instance.

  1. Select a value for Message Type. This message type defines which type of messages this topic sends and receives.

    Note: Currently, HTTP supports sending and receiving only normal messages. To send and receive messages over HTTP, select Normal messages.

The following describes the available message types:

  1. - [Normal messages](~~96359~~): Normal messages do not have any special features, differentiated from the other types of messages.
  2. - [Transactional messages](~~43348~~): MQ provides the distributed transaction function which is similar to X/Open XA. You can achieve transaction consistency with transactional messages.
  3. - [Scheduled and delayed messages](~~43349~~): Messages reach the consumer at a specific time point or after a certain period when they are sent.
  4. - [Partitionally ordered messages](~~49319~~): Messages are partitioned by sharding keys to improve overall concurrency and performance. Messages in the same partition are produced and consumed in strict FIFO order.
  5. - [Globally ordered messages](~~49319~~): All messages are produced and consumed in strict FIFO order.

Note: We recommend that you create separate topics to send messages of different types. For example, create Topic A for normal messages, Topic B for transactional messages, and Topic C for scheduled and delayed messages.

  1. In the Descriptionfield, enter remarks for the topic. Then click OK. The created topic is displayed in the topic list.

Create group IDs

After you have created an instance and a topic, you need to create a group ID for the message consumer (or producer).

Note: A group ID is required for consumers but is optional for producers.

To create a group ID, follow the steps below:

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

  2. On the Groups page, select the instance you created.

  3. Click the TCP or HTTP tab based on the protocol you need.

Note: The group ID of TCP-based instances cannot be used for HTTP-based instances and vice versa. You need to create the group IDs for TCP-based instances and for HTTP-based instances separately.

  1. Click Create Group ID.

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

Note:

  • The group ID must be unique in the same instance.

  • Group IDs and topics implement N:N mapping. A consumer can subscribe to multiple topics and a topic can be subscribed by multiple consumers. A producer can send messages to multiple topics and a topic can receive messages from multiple producers.

Create Alibaba Cloud AccessKeys

When using SDKs or calling APIs to send and subscribe to messages, you not only need to specify the topic and group ID, but also need to enter your identity verification information that you have created in the RAM console, that is, AccessKey. An AccessKey consists of an AccessKeyId and an AcessKeySecret.

For more information about how to create AccessKeys, see Create AccessKey.

Step 3: Obtain endpoints

After creating resources in the console, you need to obtain the endpoint of the instance or region in the console. To access services in an instance or a region when sending or receiving messages, you need to configure the endpoints for the producer and consumer. The endpoints vary with the protocol. The following describes the endpoints when different protocols are used:

  • TCP: The endpoint displayed in the console is the endpoint of a specific instance in the region. Different instances in the same region have different endpoints.

  • HTTP: The endpoint displayed in the console is the endpoint of a region, instead of a specific instance. You need to configure an ID for the instance when sending and receiving messages.

To view the endpoint, perform the following operations:

  1. In the left-side navigation pane, choose Instances.

  2. On the Instances page, select the instance you created.

  3. The Instance Information tab page is displayed by default. In the Endpoint Information area, you can view the endpoints of the TCP- and HTTP-based instances.

  4. In the Endpoint area of the corresponding protocol, click Copy.

As for TCP-based endpoints, you can click Sample Code to view how to set endpoints in different programming languages.

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

Step 4: Send messages

You can send messages in the console, or by using SDKs or calling APIs.

  • To quickly verify the availability of the topics, you can send messages in the console.

  • In a production environment, the SDK/API method is recommended for sending messages.

Send messages in the console

  1. In the left-side navigation pane, choose Topics.

  2. On the Topics page, locate the row that contains the topic you created and click Send in the Actions column.

  3. In the Send Message dialog box, enter the message content in the Message Body field and click OK.

The console returns a success prompt message and the corresponding message ID once the message is sent.

Send messages by using SDKs or calling APIs

In a production environment, the SDK/API method is recommended for sending messages. This topic describes how to send messages by using a Java SDK over TCP.

Note:

Send messages by using the Java SDK over TCP

  1. Use either of the following methods to add the dependency of the Java SDK:
  • Use Maven:
  1. <dependency>
  2. <groupId>com.aliyun.openservices</groupId>
  3. <artifactId>ons-client</artifactId>
  4. <version>"XXX"</version>
  5. // Enter the latest Java SDK version.
  6. </dependency>
  1. For more information about the version of the latest Java SDK, see [Release Notes](~~60953~~).
  • Download a dependency JAR package:

    For more information about the download URL of the latest Java SDK, see Release Notes.

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

    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 group ID you created in the console.
    11. properties.put(PropertyKeyConst.GROUP_ID, "XXX");
    12. // The AccessKeyId you created in the Alibaba Cloud console.
    13. properties.put(PropertyKeyConst.AccessKey,"XXX");
    14. // The AccessKeySecret you created in the Alibaba Cloud console.
    15. properties.put(PropertyKeyConst.SecretKey, "XXX");
    16. // Set the TCP endpoint: Go to the Instances page in the MQ console, select the target instance, and view the endpoint in the Endpoint Information area.
    17. properties.put(PropertyKeyConst.NAMESRV_ADDR,"XXX");
    18. Producer producer = ONSFactory.createProducer(properties);
    19. //Before sending a message, call the start() method once to start the producer.
    20. producer.start();
    21. //Send messages cyclically.
    22. while(true){
    23. Message msg = new Message( //
    24. // The topic you created in the console. This is the name of the topic to which the message belongs.
    25. "TopicTestMQ",
    26. // The message tag.
    27. // The message tag is similar to a tag in Gmail, and is used for consumers to filter messages on the MQ broker by setting filtering conditions.
    28. "TagA",
    29. // The message body.
    30. // It may be any data in binary form, and MQ makes no intervention.
    31. // The producer and consumer must negotiate the consistent serialization and deserialization methods.
    32. "Hello MQ".getBytes());
    33. // Set a key service property representing the message, that is, the message key, and try to keep it globally unique. In this way, you can query and resend the message through the MQ console when you cannot receive the message.
    34. // Note: Messages can still be sent and received if you do not set this attribute.
    35. msg.setKey("ORDERID_100");
    36. // The message is sent if no exception is thrown.
    37. // Print the message ID to facilitate querying the message sending status.
    38. SendResult sendResult = producer.send(msg);
    39. System.out.println("Send Message success. Message ID is: " + sendResult.getMessageId());
    40. }
    41. // You can destroy the producer before exiting the application.
    42. // Note: You can choose not to destroy the producer object.
    43. producer.shutdown();
    44. }
    45. }

Check whether messages are sent

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

  1. In the left-side navigation pane, choose Message Query.

  2. On the Message Query page, click 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 when the MQ broker stores the message. If the message can be queried out, the message has been sent to the broker.

Note: This step demonstrates the scenario where MQ is used for the first time, when the consumer has not been started yet. Therefore, no consumption data is displayed in the message status information. To start the consumer and subscribe to messages, see step 5. For more information about the message status, see Message Query.

Step 5: Subscribe to messages

Once a message is sent, you need to start the consumer to subscribe to messages. This topic describes how to complete message subscription by using the SDK or calling the API of the desired programming language over the target protocol. The following uses the TCP Java SDK as an example.

Note:

  • If you want to use the C/C ++ and .NET SDKs to subscribe to messages over TCP, see Subscribe to messages through C/C++ SDK and Subscribe to messages through .NET SDK.

  • If you want to subscribe to messages over HTTP, see SDK guide (HTTP) to obtain the SDK and sample code for subscribing to messages.

Subscribe to messages by using the TCP Java SDK

You can run the following sample code to start the consumer and test the message subscription function. You must set related parameters correctly according to the instructions. Currently, the console provides sample codes of Java, C++, and .NET.

  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 group ID you created in the console.
  13. properties.put(PropertyKeyConst.GROUP_ID, "XXX");
  14. // The AccessKeyId you created in the Alibaba Cloud console.
  15. properties.put(PropertyKeyConst.AccessKey, "XXX");
  16. // The AccessKeySecret you created in the Alibaba Cloud console.
  17. properties.put(PropertyKeyConst.SecretKey, "XXX");
  18. // Set the TCP endpoint: Go to the Instances page in the MQ console, select the target instance, and view the endpoint in the Endpoint Information area.
  19. properties.put(PropertyKeyConst.NAMESRV_ADDR,"XXX");
  20. Consumer consumer = ONSFactory.createConsumer(properties);
  21. consumer.subscribe("TopicTestMQ", "*", new MessageListener() {
  22. public Action consume(Message message, ConsumeContext context) {
  23. System.out.println("Receive: " + message);
  24. return Action.CommitMessage;
  25. }
  26. });
  27. consumer.start();
  28. System.out.println("Consumer Started");
  29. }
  30. }

Check whether message subscription is successful

Once the preceding steps have been completed, you can check whether the consumer has been started in the console, that is, whether the message subscription is successful.

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

  2. Locate the row that contains the group ID of the target consumer and click Consumer Status in the Actions column.

If Online is displayed, the consumer has been started. If Offline is displayed, the consumer has not been started or has failed to start.

When all the preceding steps are completed, you have accessed the MQ service and can use MQ for sending and receiving messages.