Connect a client to IoT Platform by using the SDK for Java - IoT Platform

This topic describes how to connect a Java Message Service (JMS) client that uses the Advanced Message Queuing Protocol (AMQP) protocol to Alibaba Cloud IoT Platform and receive messages IoT Platform by using the server-side subscription feature.

Prerequisites

The ID of the consumer group that subscribes to the messages of a topic is obtained.

You can use the default consumer group named DEFAULT_GROUP or create a consumer group in the IoT Platform console. For more information, see Manage consumer groups.
You can use a consumer group to subscribe to the messages of a topic. For more information, see Configure an AMQP server-side subscription.

Development environment

In this example, the development environment consists of the following components:

Operating system: Windows 10
Java Development Kit (JDK): JDK 8
Integrated development environment (IDE): IntelliJ IDEA Community Edition

Download the Apache Qpid JMS client

To download the client and view the instructions, visit Qpid JMS 0.57.0.

In this example, the following dependencies are added to a Maven project to download the Qpid JMS client:

<!-- amqp 1.0 qpid client -->
 <dependency>
   <groupId>org.apache.qpid</groupId>
   <artifactId>qpid-jms-client</artifactId>
   <version>0.57.0</version>
 </dependency>
 <!-- util for base64-->
 <dependency>
   <groupId>commons-codec</groupId>
  <artifactId>commons-codec</artifactId>
  <version>1.10</version>
</dependency>

Demo

You can use an AMQP client to receive messages from IoT Platform by using an Alibaba Cloud account or a RAM user. For example, Enterprise A has an Alibaba Cloud account named Account A and Enterprise B has an Alibaba Cloud account named Account B. Enterprise A has configured a server-side subscription in the IoT Platform console by using Account A.

Use Account A or its Resource Access Management (RAM) user that is directly granted the permissions
Note
If you use a RAM user, you must attach a RAM policy that contains the iot:sub action to the RAM user. This way, the RAM user can use the server-side subscription feature of IoT Platform. Otherwise, the connection fails. For more information, see Mapping between IoT Platform API operations and RAM policies.
To improve data security, we recommend that you use a RAM role to authorize the RAM user to use the server-side subscription feature. For more information, see the following section.
For more information, see the Receive server-side subscription messages within the current account section of this topic.
Use a RAM user that assumes a RAM role
The RAM user that you use can belong to Account A or Account B. You can use the RAM user to connect an AMQP client to IoT Platform that is activated within Account A. This way, you can receive device messages by using the server-side subscription feature.
For more information, see the Receive server-side subscription messages as a RAM user that assumes a RAM role section of this topic.

Receive server-side subscription messages within the current account

Download the demo package and decompress it.
Open IntelliJ IDEA and import the sample project amqp-demo-en in the demo package.
In the pom.xml file, the Maven dependencies have been added to download the Qpid JMS client.

In the AmqpClient.java file in the src/main/java/com.aliyun.iotx.demo directory, specify the AMQP connection parameters described in the following table.

Important

Make sure that you specify valid parameter values. Otherwise, the AMQP client fails to connect to IoT Platform.
In this example, the Thread.sleep(60 * 1000); code snippet is added to terminate the program after the program starts and runs for 1 minute. You can specify the duration based on your business requirements.

For more information, see Connect an AMQP client to IoT Platform.

Parameter	Description
accessKey	The AccessKey ID and AccessKey secret of the Alibaba Cloud account or its RAM user. Log on to the IoT Platform console, move the pointer over the profile picture in the upper-right corner, and then click AccessKey Management to obtain the AccessKey ID and AccessKey secret.
accessSecret
consumerGroupId	The ID of the consumer group of the IoT Platform instance. To view the ID of the consumer group, perform the following steps: Log on to the IoT Platform console and click the card of the instance that you want to manage. In the left-side navigation pane, choose Message Forwarding > Server-side Subscription. The ID of the consumer group is displayed on the Consumer Groups tab.
iotInstanceId	The ID of the IoT Platform instance. You can view the instance ID on the Overview tab in the IoT Platform console. If the instance ID is displayed, you must set this parameter to the instance ID. If the Overview tab is not displayed or your instance does not have an ID, leave this parameter empty in the format of `iotInstanceId = ""`.
clientId	The ID of the client. You must specify a custom ID. The ID must be 1 to 64 characters in length. We recommend that you use a unique identifier as the client ID, such as the UUID, MAC address, or IP address of the server on which the client runs. After the AMQP client is connected to IoT Platform and started, perform the following steps to view the details of the client: Log on to the IoT Platform console and click the card of the instance that you want to manage. In the left-side navigation pane, choose Message Forwarding > Server-side Subscription. On the Consumer Groups tab, find the consumer group that you want to manage and click View in the Actions column. The ID of each client is displayed on the Consumer Group Status tab. You can use client IDs to identify clients with ease.
connectionCount	The number of connections that are enabled on the AMQP client. Maximum value: 128. This parameter is used for scale-out in real-time message pushing scenarios. On the Consumer Group Details page, each connected client is displayed as `${clientId}+"-"+ Number`. The minimum number is 0.
host	The endpoint that the AMQP client uses to connect to IoT Platform. For more information about the endpoint that you can specify for the `${YourHost}` variable, see Manage the endpoint of an instance.

Run the AmqpClient.java program.
- If information similar to the following output is displayed, the AMQP client is connected to IoT Platform and can receive messages:
```
topic = /***********/******/thing/event/property/post,
message = 2**************7,
content = {"temperature":29,"humidity":29,"time":1617357297270}
```
  Parameter
  Description
  topic
  The topic that is used to submit device properties.
  messageId
  The ID of the message.
  content
  The content of the message.
- If an error occurs in the code or network environment, the AMQP client fails to connect to IoT Platform.
  You can check the code or network environment based on logs, resolve the issue, and then run the code again.

Receive server-side subscription messages as a RAM user that assumes a RAM role

Prerequisites

The RAM user is assigned the RAM role to access the IoT Platform server-side subscription resources that belong to Account A. For more information, see Authorize a RAM user of the current Alibaba Cloud account to use server-side subscription and Authorize a RAM user of another account to use server-side subscription.

Procedure

Download the demo package and decompress it.
Open IntelliJ IDEA and import the sample project amqp-sts-demo in the demo package.
In the pom.xml file, the Maven dependencies have been added to download the Qpid JMS client.

In the AmqpStsTokenClient.java file in the src/main/java/com/aliyun/iotx/demo directory, specify the AMQP connection parameters described in the following table.

Important

Make sure that you specify valid parameter values. Otherwise, the AMQP client fails to connect to IoT Platform.
A Security Token Service (STS) token is valid for up to 1 hour. You must update the AMQP connection parameters on a regular basis to ensure that the AMQP client can reconnect to IoT Platform as expected. For more information, see the scheduledExecutorService.scheduleAtFixedRate section in the demo code.
In this example, the Thread.sleep(6000 * 1000); code snippet is added to terminate the program after the program starts and runs for 1 minute. You can specify the duration based on your business requirements.

For more information, see Connect an AMQP client to IoT Platform.

Parameter	Description
CONNECTION_COUNT	The number of connections that are enabled on the AMQP client. Maximum value: 128. This parameter is used for scale-out in real-time message pushing scenarios. On the Consumer Group Details page in the IoT Platform console, each connected client is displayed as `"clientId-"+ Number`. The minimum number is 0.
DURATION_SECONDS	The validity period of the STS token. The validity period cannot exceed 1 hour. Valid values: 15 to 60. Unit: minutes.
STS_ENDPOINT	The endpoint that is used to obtain the STS token. For more information, see Endpoints.
STS_ACCESS_KEY	The AccessKey ID and AccessKey secret of the RAM user that assumes the RAM role of Account A.
STS_ACCESS_SECRET
STS_ROLE_ARN	The Alibaba Cloud Resource Name (ARN) of the RAM role to be assumed. Format: `acs:ram::<account-id>:role/<role-name>`. `<role-name>` is the name of the RAM role in lowercase. After you create a RAM role, you can click the role name to view the ARN in the Basic Information section.
CONSUMER_GROUP_ID	The ID of the consumer group that subscribes to the server-side subscription messages. To view the consumer group ID, perform the following steps: Log on to the IoT Platform console and click the card of the instance that you want to manage. In the left-side navigation pane, choose Message Forwarding > Server-side Subscription. The ID is displayed on the Consumer Groups tab.
IOT_INSTANCE_ID	The ID of the IoT Platform instance within Account A. You can log on to the IoT Platform console and view the instance ID on the Overview tab. If the instance ID is displayed, you must set this parameter to the instance ID. If the Overview tab is not displayed or your instance does not have an ID, leave this parameter empty in the format of `IOT_INSTANCE_ID = ""`.
HOST	The endpoint that the AMQP client uses to connect to the IoT Platform instance within Account A. For more information, see Manage the endpoint of an instance.

Run the AmqpStsTokenClient.java program.
- If information similar to the following output is displayed, the AMQP client is connected to IoT Platform and can receive messages:
```
topic = /***********/******/thing/event/property/post,
message = 2**************7,
content = {"temperature":29,"humidity":29,"time":1617357297270}
```
  Parameter
  Description
  topic
  The topic that is used to submit device properties.
  messageId
  The ID of the message.
  content
  The content of the message.
- If an error occurs in the code or network environment, the AMQP client fails to connect to IoT Platform.
  You can check the code or network environment based on logs, resolve the issue, and then run the code again.

References

For more information about the error codes that are related to the server-side subscription feature, see the Error codes that are related to messages section of the "IoT Platform logs" topic.

Parameter	Description
topic	The topic that is used to submit device properties.
messageId	The ID of the message.
content	The content of the message.