After you configure AMQP service subscription in the IoT Platform console, connect the AMQP client to the console by referring to this topic. In this way, the AMQP client running on your server can receive device messages.

Protocol version

For more information, see AMQP.

Service subscription of Alibaba Cloud IoT Platform only complies with AMQP 1.0.

Establish the connection and perform authentication

  1. First, the AMQP client and IoT Platform establish a TCP connection through a three-way handshake. Then, TLS handshake authentication is implemented.
    Note To ensure security, the recipient must use TLS encryption. Unencrypted transmission over TCP connections is not allowed.
  2. The client requests to establish a connection.

    PLAIN-SASL is used for connection authentication, which authenticates the userName and password fields in requests. After the userName and password authentication succeeds on IoT Platform, the connection is established.

    According to the AMQP, when the client attempts to establish a connection with IoT Platform, the heartbeat time (the Idle-time-out parameter in the AMQP) must be carried in the Open frame. The heartbeat time ranges from 30,000 to 300,000, in milliseconds. IoT Platform closes the connection if there is no communication frame over the connection after the heartbeat time expires. The method for setting the Idle-time-out parameter varies according to SDK. For more information, see demos of SDKs in different programming languages.

  3. The client sends a request to IoT Platform to establish a receiver link. It is a one-way channel for IoT Platform to push data to the client.

    The client must establish the receiver link in 15 seconds after the connection is established. Otherwise, IoT Platform closes the connection.

    After the receiver link is established, the client is connected to IoT Platform.

    Note
    • One receiver link can be created over one connection. Sender links are not allowed. Only IoT Platform can push messages to the client, but the client cannot send messages to IoT Platform.
    • In some SDKs, the receiver link is referred to as MessageConsumer.

Configure connections

The URL and authentication parameters used for the AMQP client to access IoT Platform are described as follows:

  • Endpoint: amqps://${uid}.iot-amqp.${regionId}.aliyuncs.com
    Table 1. Variables in the domain name
    Variable Description
    uid The ID of your Alibaba Cloud account.

    To obtain the account ID, log on to the Alibaba Cloud console by using your Alibaba Cloud account, and click the account avatar. The Security Settings page of the Account Management console appears.

    regionId The region ID of your IoT Platform service.

    You can view the region in the upper-right corner of the IoT Platform console. For information about RegionId expressions, see Regions and zones.

  • Port: 5671
  • Client authentication parameters:
    userName = clientId|authMode=aksign,signmethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
    password = signmethod(stringToSign, accessSecret)
    Table 2. userName parameters
    Parameter Required Description
    clientId Yes The client ID. We recommend that you use a unique identifier, such as the UUID, MAC address, or IP address of the client machine. The value can be up to 64 characters in length.

    This parameter is displayed on the Consumer Group Status tab of Service Subscription in the console, allowing you to identify clients.

    authMode Yes The authentication mode. Currently, only the aksign mode is supported.
    signMethod Yes The signature algorithm. Valid values: hmacmd5, hmacsha1, and hmacsha256.
    consumerGroupId Yes The ID of a consumer group. You can view the IDs of your consumer groups in the console.
    authId Yes The authentication information. In aksign authentication mode, the value of the authId parameter is the AccessKey ID of your Alibaba Cloud account.

    To obtain the AccessKey ID, log on to the Alibaba Cloud console, move the pointer over your account avatar, and click AccessKey. The Security Management page of the User Management console appears.

    timestamp Yes The current time. The timestamp is a long integer in milliseconds.
    cleanSession No Indicates whether accumulated offline messages are cleared. Valid values:
    • true: clear
    • false: not clear

    If you do not specify this parameter, the default value false is used.

    Table 3. password parameters
    Parameter Required Description
    signmethod Yes The signature algorithm. Use the signature algorithm specified in userName to calculate the signature value and convert the value to a Base64-encoded string.
    stringToSign Yes The string to be signed.

    Alphabetically arrange the key-value pairs of the parameters you want to sign, use an equal sign (=) between the key and value, and use an ampersand (&) between the parameters.

    The parameters to be signed include authId and timestamp.

    The string to be signed is authId=${accessKey}&timestamp=1573489088171.

    accessSecret Yes The AccessKey secret of your Alibaba Cloud account.

    To obtain the AccessKey secret, log on to the Alibaba Cloud console, move the pointer over your account avatar, and click AccessKey. The Security Management page of the User Management console appears.

Receive messages from IoT Platform

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

Messages pushed by IoT Platform to the client:

  • Message body: The payload of the message is in binary format.
  • Message attributes: include the message topic and message ID. You can obtain them from the AMQP parameter Application Properties. The attributes are in the format of key:value.
    Key Description
    topic The message topic
    messageId The message ID
    generateTime The time when the message was generated

Message receipt:

According to the AMQP, the client must send a receipt (referred to as a settle in the AMQP) to IoT Platform to notify IoT Platform of successful message reception. The AMQP client has automatic and manual receipt modes. We recommend that you use the automatic receipt mode. For more information, see the instructions for using the corresponding client.

Message policies:
  1. Real-time messages are directly pushed.
  2. Messages are accumulated due to push rate limiting or failures. Accumulated messages are re-sent.
  3. Accumulated messages are re-sent. If the recipient returns an ACK packet, the next message window is triggered immediately.
  4. IoT Platform determines whether a message is received based on the ACK packet from the client device. If IoT Platform does not receive an ACK packet, the message is accumulated and then re-sent.
Note
  • The order of messages is not preserved. You can use timestamps to order services.
  • Messages can be sent repeatedly. A message is repeatedly sent until the peer end confirms the reception or it expires. You can deduplicate messages based on IDs.
  • You can set cleanSession on the client to clear accumulated messages each time the client goes online. For more information, see the demo of AMQP service subscription.

References

Limits

Java SDK access example

Node.js SDK access example

.NET SDK access example

Python SDK access example