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 on your business server.

Protocol versions

For more information, see AMQP.

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

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.

    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.

    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, IoT Platform ends 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.

  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 based on the programming language of the SDK. For example, the receiver link in some SDKs is named MessageConsumer in some SDKs.

Connect the AMQP client to IoT Platform

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

  • Endpoint: 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 View 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.
  • 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 1. Parameters in userName
    Parameter Required Description
    clientId Yes The ID of the client. We recommend that you 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 and click the card of the instance that you want to manage. Choose Rules Engine > Server-side Subscription > Consumer Groups. 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 Details page. You can use client IDs to efficiently identify clients.

    iotInstanceId No The ID of the instance. You can view the instance ID on the Overview page in the IoT Platform console.
    • If your instance has an ID, you must specify the ID for the parameter.
    • If your instance does not have an ID, you do not need to configure the parameter.
    authMode Yes The authentication mode. Valid value: aksign.
    signMethod Yes The signature algorithm. Valid values: hmacmd5, hmacsha1, and hmacsha256.
    consumerGroupId Yes The ID of the consumer group.

    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 manange. Choose Rules Engine > Server-side Subscription > Consumer Groups. The ID is displayed on the Consumer Groups tab.

    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 your profile picture, and then click AccessKey Management. On the page that appears, obtain the AccessKey ID.

    Note If you use the AccessKey ID of a RAM user, you must grant the RAM user the permissions to configure AMQP server-side subscription. Otherwise, the connection fails. For more information about the authorization methods, see Authorize a RAM user to access IoT Platform.
    timestamp Yes The current time. The timestamp is a LONG integer. Unit: milliseconds.
    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 (&).

    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 your 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, you must grant the RAM user the permissions to configure AMQP server-side subscription. Otherwise, the connection fails. For more information about the authorization methods, see Authorize a RAM user to access IoT Platform.

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 Connect the AMQP client to IoT Platform.

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

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 of the types that are specified in the subscription. If you want 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 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.
  • 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.
    • 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. 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 you forward 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 of server-side subscriptions.
  • You can clear accumulated messages in the IoT Platform console. For more information, see View and monitor consumer groups.
Message ordering:
Note The ordering of messages cannot be ensured.
  • Upstream and downstream device messages:

    The time when a message is received from a device is different from the time when the device is connected or disconnected. You can sort messages by the value of the Time parameter.

    For example, you obtain 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 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 to process the message.