This article 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.

Protocol versions

For more information, see AMQP.

Server-side subscriptions of Alibaba Cloud IoT Platform complies only with AMQP 1.0.

Procedure

  1. 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.
  2. The client requests to establish a connection.

    PLAIN SASL 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.

    AMQP requires that the open frame includes the idle-time-out field when a connection is established. This field specifies the heartbeat timeout period. The heartbeat timeout period ranges from 30,000 to 300,000 ms. If no frame is transmitted over the connection after the heartbeat timeout period expires, then IoT Platform ends the connection. The method that is used to set the idle-time-out field varies with the programming language of the SDK. For more information, see the sample code of language-specific SDKs.
    Note If the connection is established by using an Alibaba Cloud SDK, the server does not need to send ping packets to maintain the connection. During the keep-alive time that is provided by the SDK, make sure that the main process does not exit.
  3. 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 ends 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 with the programming language of the SDK. For example, the receiver link is named MessageConsumer in some SDKs.

Configurations

This section describes the endpoints and authentication parameters that the AMQP client can use to access IoT Platform.

  • Endpoints:
    • The endpoint for public instances is in the ${uid}.iot-amqp.${regionId}.aliyuncs.com format.
      Table 1. The following table describes the variables that are used in public instances.
      Variable Description
      uid The ID of your Alibaba Cloud account.

      To view the ID of the Alibaba Cloud account, log on to the IoT Platform console, and click the profile picture in the upper-right corner of the page to go to the Security Settings page.

      regionId The ID of the region where IoT Platform runs.

      You can view the region in the upper-left corner of the IoT Platform console. For more information about the format of the RegionId parameter, see Regions and zones.

    Note
    • The ${YourHost} variable of the SDK specifies your endpoint.
    • When you connect to a purchased instance, make sure that the required product and device are created in the instance.
  • Port number:
    • 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 PHP client, the port number is 61614.
  • Client-side authentication parameters:
    userName = clientId|iotInstanceId=${iotInstanceId},authMode=aksign,signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
    password = signMethod(stringToSign, accessSecret)
    Table 2. The following table describes the composition of the userName parameter.
    Parameter Required Description
    clientId Yes The client ID. You must use a unique identifier, such as the UUID, MAC address, or IP address of the client. The client ID must be 1 to 64 characters in length.

    Log on to the IoT Platform console. Choose Rules > Server-side Subscription > Consumer Groups, and click View next to the required consumer group. The Consumer Group Details shows the parameter. This parameter allows you to identify clients.

    iotInstanceId No The instance ID. This parameter is required when you use a purchased instance. If you use a public instance, this parameter is optional.
    authMode Yes The authentication mode. Valid value: aksign.
    signMethod Yes The signature algorithm. Valid values: hmacmd5, hmacsha1, and hmacsha256.
    consumerGroupId Yes The consumer group ID.

    Log on to the IoT Platform console. Choose Rules > Server-side Subscription > Consumer Groups and view the ID of the required consumer group.

    authId Yes The authentication information. In aksign authentication mode, set the authId parameter to your AccessKey ID.

    Log on to the IoT Platform console, move the pointer over the profile picture, and then click AccessKey Management. On the page that appears, obtain the required AccessKey ID.

    Note If you use the AccessKey ID of a RAM user, the RAM user must have the AliyunIOTFullAccess permission on IoT Platform. Otherwise, the connection fails. For more information about the authorization methods, see Authorize a RAM user to access IoT Platform.
    timestamp Yes The timestamp. The timestamp is a LONG integer. Unit: milliseconds.
    Table 3. The following table describes the composition of the password parameter.
    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, you can 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 (&).

    The parameters that must be signed include authId and timestamp.

    Set the stringToSign parameter to a value in the stringToSign = authId=${accessKey}&timestamp=1573489088171 format.

    accessSecret Yes The AccessKey secret of you Alibaba Cloud account.

    Log on to the IoT Platform console, move the pointer over the profile picture, and then click AccessKey Management. On the page that appears, obtain the required AccessKey ID.

    Note If you use the AccessKey ID of a RAM user, the RAM user must have the AliyunIOTFullAccess permission on IoT Platform. Otherwise, the connection fails. For more information about the authorization methods, see Authorize a RAM user to access IoT Platform.

Examples

You can use the following language-specific AMQP SDKs to connect a client to IoT Platform. For more information about how to set the parameters, see Configurations.

When you connect a client, you may receive message-related error codes. For more information, see Message-related error codes.

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 to which IoT Platform subscribes. If you need to send messages or commands to a device, you can call the required operation. For more information, see List of operations by function.

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

  • Message body. The payload of the message is in binary format.
  • Message attributes such as topic and message ID. You can obtain the attributes from the application-properties that are defined in AMQP. The attributes are in the key:value format.
    Key Description
    topic The message topic.
    messageId The message ID.
    generateTime The time when the message was generated.
    Note You cannot determine the order of messages based on the generateTime parameter.

Message receipt:

AMQP requires that the client sends a receipt (referred to as a settle in AMQP) to IoT Platform. The receipt is used 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.
  • Accumulated messages

    Messages may not be consumed in real time due to some issues. In this case, these messages are accumulated. These issues include that consumers disconnect from IoT Platform and the speed at which these messages are consumed is slow.

    • After these consumers re-connect to IoT Platform and start to consume messages at a stable speed, IoT Platform pushes accumulated messages to these consumers again.
    • If consumers fail to consume these pushed messages, the queue where accumulated messages reside may be blocked. After an interval of about 1 minute, IoT Platform retries to push accumulated messages to consumers.
Note
  • The amount of traffic that consumers process may fluctuate during a short period of time. This issue is normal. 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 some level of redundancy in message consumption.
  • When you forward a message, the message may be repeatedly sent until the client returns ACK or the message expires. If multiple messages have the same message ID, you can deduplicate the messages based on the ID.
  • For more information about limits on messaging, see Limits on server-side subscriptions.
  • You can clear accumulated messages in the IoT Platform console. For more information, see View and monitor consumer groups.
Timing:
Note The order of messages is not preserved.
  • Upstream and downstream device messages:

    The time when a message is received from a device is not equal to the time when the device status changes. You can check the time when the status of a device changes based on the lastTime parameter.

    For example, you receive 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 three messages indicate that the status of a device changed to offline, online, and then offline.

    For more information about the parameters of these messages, see Data formats.

  • Other types of messages:

    You need to add a serial number to each message at the business layer. Based on the serial number of a received message, the system checks whether to process the message through an idempotent algorithm.