Connect an AMQP client to IoT Platform - IoT Platform - Alibaba Cloud Documentation Center

This topic describes how to connect an Advanced Message Queuing Protocol (AMQP) client to IoT Platform. You can perform this operation after you configure an AMQP server-side subscription in the IoT Platform console. After you connect an AMQP client to IoT Platform, you can receive device messages by using the AMQP client on your business server.

Limits

For more information about AMQP, visit the AMQP official website.

The server-side subscriptions of IoT Platform support only the AMQP 1.0 protocol.

Connect to IoT Platform

An AMQP client establishes a TCP connection with IoT Platform by using a three-way handshake. Then, a TLS handshake is performed to authenticate the AMQP client.
Note
To ensure security, AMQP clients must transmit data by using TLS encryption. Data cannot be transmitted over unencrypted TCP channels.
The client requests to establish a connection.
The PLAIN SASL mechanism is used to authenticate the connection. The authentication is based on a username and password. After the username and password-based authentication is passed by IoT Platform, the connection is established.
Based on AMQP, the client must add the idle-time-out field to the open frame when the client establishes a connection. This field specifies the heartbeat timeout period. The heartbeat timeout period ranges from 30,000 ms to 300,000 ms. If no frame is transmitted over the connection after the heartbeat timeout period expires, IoT Platform closes the connection. The method that is used to configure the idle-time-out field varies based on the programming language of the SDK. For more information, see the sample code of language-specific SDKs.
The client sends a request to IoT Platform to establish a receiver link. The receiver link is a one-way channel that you can use to push data from IoT Platform to the client.
The client must establish the receiver link within 15 seconds after the AMQP connection is established. Otherwise, IoT Platform closes the AMQP connection.
After the receiver link is established, the client is connected to IoT Platform.
Note
- Only one receiver link can be created for each connection. Sender links are not supported. IoT Platform can push messages to the client, but the client cannot send messages to IoT Platform.
- The class name of the receiver link varies based on the programming language of the SDK. For example, the receiver link is named MessageConsumer in some SDKs.

Connection settings

This section describes how to specify the endpoint and configure the authentication parameters when you connect an AMQP client to IoT Platform.

Endpoint and port

Specify the endpoint of a public instance or an Enterprise Edition instance to which you want to connect an AMQP client. For more information about the supported endpoints, see Manage the endpoint of an instance.

Note

The ${YourHost} variable in the SDK specifies the endpoint.

Before you connect the client to an IoT Platform instance, make sure that your product and device are created in the instance.

If you use a Java, .NET, Python 2.7, Node.js, or Go client, the port number is 5671.
If you use a Python 3 or a PHP client, the port number is 61614.

Authentication parameters

The authentication parameters that you need to configure vary based on the Alibaba Cloud identity that you use to connect an AMQP client to IoT Platform.

If you use the Alibaba Cloud account to which the IoT Platform instance belongs or a Resource Access Management (RAM) user that is directly granted the required permissions within the Alibaba Cloud account, you must configure the following authentication parameters:
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.
```
userName = clientId|iotInstanceId=${iotInstanceId},authMode=aksign,signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
password = signMethod(stringToSign, accessSecret)
```

If you use a RAM user that is authorized by a RAM role, you must configure the following authentication parameters:

Note

In addition to the RAM users of the Alibaba Cloud account to which the IoT Platform instance belongs, you can use a RAM role to authorize a RAM user of another Alibaba Cloud account to use the server-side subscription feature. For more information about how to use a RAM role to authorize a RAM user to use the server-side subscription feature of IoT Platform, 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.

userName = clientId|iotInstanceId=${iotInstanceId},authMode=ststoken,securityToken=${SecurityToken},signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
password = signMethod(stringToSign, accessSecret)

Table 1. Parameters in userName

Parameter	Required	Description
clientId	Yes	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.
iotInstanceId	No	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, you do not need to specify this parameter.
authMode	Yes	The authentication mode. If you use the Alibaba Cloud account to which the IoT Platform instance belongs or a RAM user that is directly granted the required permissions within the Alibaba Cloud account, use the `aksign` mode. If you use a RAM user that is authorized by a RAM role, use the `ststoken` mode.
securityToken	No	Important This parameter is required only if you use a RAM user that is authorized by a RAM role to connect the AMQP client to IoT Platform. The Security Token Service (STS) token that is assigned to the RAM user that assumes the RAM role. You can call the AssumeRole operation to obtain the STS token. For more information, see AssumeRole.
signMethod	Yes	The signature algorithm. Valid values: `hmacmd5`, `hmacsha1`, and `hmacsha256`.
consumerGroupId	Yes	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.
authId	Yes	The authentication information. If you use the Alibaba Cloud account to which the IoT Platform instance belongs or a RAM user that is directly granted the required permissions within the Alibaba Cloud account: Set this parameter to the AccessKey ID of the Alibaba Cloud account or the AccessKey ID of the RAM user. Log on to the IoT Platform console, move the pointer over your profile picture, and then click AccessKey Management. On the page that appears, obtain the AccessKey ID. If you use a RAM user that is authorized by a RAM role: Set this parameter to the AccessKey ID of the RAM user that assumes the RAM role.
timestamp	Yes	The current time. The timestamp is a LONG integer. Unit: millisecond.

Table 2. Parameters in password
Parameter	Required	Description
signMethod	Yes	The signature algorithm. Use the signature algorithm that is specified in the userName parameter to calculate the signature value. Then, convert the value into a Base64-encoded string.
stringToSign	Yes	The string to sign. Sort the parameters that must be signed in alphabetical order. Concatenate the key and value of each parameter by using an equal sign (=). Concatenate the parameters by using an ampersand (&). If you use the Alibaba Cloud account to which the IoT Platform instance belongs or a RAM user that is directly granted the required permissions within the Alibaba Cloud account: The parameters that must be signed include `authId` and `timestamp`. Set the value in the `stringToSign = authId=${accessKey}&timestamp=1573489088171` format. If you use a RAM user that is authorized by a RAM role: The parameters that must be signed include `securityToken`, `authId`, and `timestamp`. Set the value in the `stringToSign = authId=${accessKey}&securityToken=${SecurityToken}&timestamp=1573489088171` format.
accessSecret	Yes	If you use the Alibaba Cloud account to which the IoT Platform instance belongs or a RAM user that is directly granted the required permissions within the Alibaba Cloud account: Set this parameter to the AccessKey secret of the Alibaba Cloud account or the AccessKey secret of the RAM user. Log on to the IoT Platform console, move the pointer over your profile picture, and then click AccessKey Management. On the page that appears, obtain the AccessKey secret. If you use a RAM user that is authorized by a RAM role: Set this parameter to the AccessKey secret of the RAM user that assumes the RAM role.

Receive messages that are pushed by IoT Platform

After a receiver link is established between an AMQP client and IoT Platform, IoT Platform pushes messages to the client over the link.

Note

A client can receive only messages of the types that are specified in the subscription. If you want to send messages or commands to a device, call the corresponding operation based on your business requirements. For more information, see List of operations by function.

Each message that is pushed by IoT Platform to the client consists of the following parts:

Message body. The payload of the message is in the binary format.

Message attributes, such as topic and message ID. You can obtain the attributes from the application-properties section that is defined in AMQP. The attributes are in the key:value format.

Key	Description
topic	The topic of the message.
messageId	The ID of the message.
generateTime	The time when the message was generated. Note You cannot determine the order of messages based on the generateTime parameter.

Message receipt:

The AMQP client sends a receipt to IoT Platform to notify IoT Platform that a message is received. The receipt can be manually or automatically sent. We recommend that you use the automatic mode. For more information, see the user guide of the client.

Messaging policies:

Messages are pushed in real time.
Messages are accumulated.
Messages may not be consumed in real time due to specific issues. For example, if consumers disconnect from IoT Platform or messages are consumed at a low speed, messages are accumulated in these cases.
- After disconnected consumers re-connect to IoT Platform and start to consume messages at a stable speed, IoT Platform pushes the accumulated messages to the consumers.
- If consumers fail to consume the pushed messages, the queue in which accumulated messages reside may be blocked. When the messages fail to be consumed, IoT Platform retries to push the accumulated messages to the consumers after approximately 1 minute.

Note

The amount of traffic that consumers process may fluctuate during a short period of time. In most cases, the fluctuation disappears within 10 minutes. If the number of queries per second (QPS) is high or the message processing is resource-consuming, we recommend that you increase the number of consumers. This way, you can maintain an acceptable level of redundancy in message consumption.
When IoT Platform forwards a message, the message may be repeatedly sent until the client returns an ACK message or the message expires. If multiple messages use the same message ID, you can deduplicate the messages based on the ID.
For more information about the limits on messaging, see Limits on server-side subscriptions.
You can clear accumulated messages in the IoT Platform console. For more information, see the View and monitor consumer groups section of the "Manage consumer groups" topic.

Message ordering:

Note

The ordering of messages is not guaranteed. Therefore, the messages may not be received in order by the time when the messages were generated.

Upstream and downstream device messages:
The returned messages are not sorted by time. You need to manually sort the messages.
For example, you received the following messages in sequence:
1. Online time: 2018-08-31 10:02:28.195
2. Offline time: 2018-08-31 10:01:28.195
3. Offline time: 2018-08-31 10:03:28.195
The preceding messages indicate that the device was disconnected, reconnected, and then disconnected again.
For more information about the parameters in messages, see Data formats.
Other types of messages:
You must add a sequence number to each message at the application layer. Based on the sequence number of a received message, IoT Platform uses an idempotent algorithm to check whether the message needs to be processed.

Examples

You can use one of the following programming language-specific AMQP SDKs to connect a client to IoT Platform. For more information about how to configure the parameters, see the Connection settings section of this topic.

Important

We recommend that you use the AMQP SDKs provided by IoT Platform. Alibaba Cloud does not provide technical support for self-developed AMQP SDKs.

When you connect a client to IoT Platform, you may receive message-related error codes. For more information, see the Error codes that are related to messages section of the "IoT Platform logs" topic.