IoT Platform:Connecter un client AMQP à IoT Platform

Limites

Les abonnements côté serveur d'IoT Platform prennent uniquement en charge le protocole AMQP 1.0.

Connexion à IoT Platform

1. Le client AMQP établit une connexion TCP avec IoT Platform par une négociation en trois temps (three-way handshake), puis effectue une négociation TLS pour s'authentifier.

   Remarque

   Pour garantir la sécurité, les clients AMQP doivent chiffrer les données via TLS. La transmission de données via des canaux TCP non chiffrés est impossible.

2. Le client demande l'établissement de la connexion.

   L'authentification de la connexion repose sur le mécanisme PLAIN SASL, qui utilise un nom d'utilisateur et un mot de passe. IoT Platform valide ces identifiants avant d'établir la connexion.

   Conformément au protocole AMQP, le client doit ajouter le champ idle-time-out à la trame d'ouverture lors de l'établissement de la connexion. Ce champ spécifie le délai d'expiration du signal de présence (heartbeat), compris entre 30 000 ms et 300 000 ms. Si aucune trame n'est transmise sur la connexion après l'expiration de ce délai, IoT Platform ferme la connexion. La méthode de configuration du champ idle-time-out varie selon le langage de programmation du SDK. Pour plus d'informations, consultez les exemples de code des SDK spécifiques à chaque langage.

3. Le client envoie une requête à IoT Platform pour établir un lien de réception (receiver link). Il s'agit d'un canal unidirectionnel permettant de transférer les données d'IoT Platform vers le client.

   Le client doit établir le lien de réception dans les 15 secondes suivant l'établissement de la connexion AMQP. À défaut, IoT Platform ferme la connexion AMQP.

   Une fois le lien de réception établi, le client est connecté à IoT Platform.

   Remarque

   • Un seul lien de réception peut être créé par connexion. Les liens d'envoi (sender links) ne sont pas pris en charge. IoT Platform peut envoyer des messages au client, mais le client ne peut pas envoyer de messages à IoT Platform.

   • Le nom de classe du lien de réception varie selon le langage de programmation du SDK. Par exemple, le lien de réception est nommé MessageConsumer dans certains SDK.

Paramètres de connexion

Cette section décrit comment spécifier le point de terminaison et configurer les paramètres d'authentification lors de la connexion d'un client AMQP à IoT Platform.

Point de terminaison et port

Spécifiez le point de terminaison de l'instance publique ou de l'instance Enterprise Edition à laquelle vous souhaitez connecter un client AMQP. Pour plus d'informations sur les points de terminaison pris en charge, consultez Gérer les points de terminaison des instances.

• Si vous utilisez un client Java, .NET, Python 2.7, Node.js ou Go, le numéro de port est 5671.

• Si vous utilisez un client Python 3 ou PHP, le numéro de port est 61614.

Paramètres d'authentification

Les paramètres d'authentification à configurer varient selon l'identité Alibaba Cloud utilisée pour connecter un client AMQP à IoT Platform.

• Si vous utilisez le compte Alibaba Cloud auquel appartient l'instance IoT Platform ou un utilisateur RAM auquel les autorisations requises ont été directement accordées au sein de ce compte Alibaba Cloud, vous devez configurer les paramètres d'authentification suivants :

  Remarque

  Si vous utilisez un utilisateur RAM, vous devez attacher à cet utilisateur une stratégie RAM contenant l'action iot:sub. Cela permet à l'utilisateur RAM d'utiliser la fonctionnalité d'abonnement côté serveur d'IoT Platform. Dans le cas contraire, la connexion échoue. Pour plus d'informations, consultez Autorisation RAM pour IoT Platform.

  Pour améliorer la sécurité des données, nous vous recommandons d'utiliser un rôle RAM pour autoriser l'utilisateur RAM à utiliser la fonctionnalité d'abonnement côté serveur. Pour plus d'informations, consultez la section suivante.

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

• Si vous utilisez un utilisateur RAM autorisé par un rôle RAM, vous devez configurer les paramètres d'authentification suivants :

  Remarque

  Outre les utilisateurs RAM du compte Alibaba Cloud auquel appartient l'instance IoT Platform, vous pouvez utiliser un rôle RAM pour autoriser un utilisateur RAM d'un autre compte Alibaba Cloud à utiliser la fonctionnalité d'abonnement côté serveur. Pour plus d'informations sur l'utilisation d'un rôle RAM pour autoriser un utilisateur RAM à utiliser la fonctionnalité d'abonnement côté serveur d'IoT Platform, consultez Autoriser un utilisateur RAM du compte Alibaba Cloud actuel à utiliser l'abonnement côté serveur et Autoriser un utilisateur RAM d'un autre compte à utiliser l'abonnement côté serveur.

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

  Tableau 1. Paramètres dans userName

  Paramètre	Obligatoire	Description
  clientId	Oui	ID du client. Vous devez spécifier un ID personnalisé. Sa longueur doit être comprise entre 1 et 64 caractères. Nous vous recommandons d'utiliser un identifiant unique comme ID client, tel que l'UUID, l'adresse MAC ou l'adresse IP du serveur sur lequel s'exécute le client. Une fois le client AMQP connecté et démarré sur IoT Platform, suivez les étapes ci-dessous pour afficher les détails du client : connectez-vous à la console IoT Platform et cliquez sur la carte de l'instance que vous souhaitez gérer. Dans le volet de navigation de gauche, choisissez Message Forwarding > Server-side Subscription. Sous l'onglet Consumer Groups, repérez le groupe de consommateurs à gérer et cliquez sur View dans la colonne Actions. L'ID de chaque client s'affiche sous l'onglet Consumer Group Status. Les ID client vous permettent d'identifier facilement les clients.
  iotInstanceId	Non	ID de l'instance IoT Platform. Vous pouvez consulter l'ID de l'instance sous l'onglet Overview de la console IoT Platform. Si l'ID de l'instance s'affiche, vous devez définir ce paramètre sur l'ID de l'instance. Si l'onglet Overview ne s'affiche pas ou si votre instance ne possède pas d'ID, il n'est pas nécessaire de spécifier ce paramètre.
  authMode	Oui	Mode d'authentification. Si vous utilisez le compte Alibaba Cloud auquel appartient l'instance IoT Platform ou un utilisateur RAM auquel les autorisations requises ont été directement accordées au sein de ce compte Alibaba Cloud, utilisez le mode aksign. Si vous utilisez un utilisateur RAM autorisé par un rôle RAM, utilisez le mode ststoken.
  securityToken	Non	Important Ce paramètre est requis uniquement si vous utilisez un utilisateur RAM autorisé par un rôle RAM pour connecter le client AMQP à IoT Platform. Jeton STS (Security Token Service) attribué à l'utilisateur RAM qui assume le rôle RAM. Vous pouvez appeler l'opération AssumeRole pour obtenir le jeton STS. Pour plus d'informations, consultez AssumeRole.
  signMethod	Oui	Algorithme de signature. Valeurs possibles : hmacmd5, hmacsha1 et hmacsha256.
  consumerGroupId	Oui	ID du groupe de consommateurs de l'instance IoT Platform. Pour afficher l'ID du groupe de consommateurs, procédez comme suit : connectez-vous à la console IoT Platform et cliquez sur la carte de l'instance que vous souhaitez gérer. Dans le volet de navigation de gauche, choisissez Message Forwarding > Server-side Subscription. L'ID du groupe de consommateurs s'affiche sous l'onglet Consumer Groups.
  authId	Oui	Informations d'authentification. Si vous utilisez le compte Alibaba Cloud auquel appartient l'instance IoT Platform ou un utilisateur RAM auquel les autorisations requises ont été directement accordées au sein de ce compte Alibaba Cloud : Définissez ce paramètre sur l'AccessKey ID du compte Alibaba Cloud ou sur l'AccessKey ID de l'utilisateur RAM. Connectez-vous à la console IoT Platform, placez le curseur sur votre photo de profil, puis cliquez sur AccessKey Management. Sur la page qui s'affiche, récupérez l'AccessKey ID. Si vous utilisez un utilisateur RAM autorisé par un rôle RAM : Définissez ce paramètre sur l'AccessKey ID de l'utilisateur RAM qui assume le rôle RAM.
  timestamp	Oui	Heure actuelle. L'horodatage est un entier LONG. Unité : milliseconde.

  Tableau 2. Paramètres dans password

  Paramètre	Obligatoire	Description
  signMethod	Oui	Algorithme de signature. Utilisez l'algorithme de signature spécifié dans le paramètre userName pour calculer la valeur de signature. Convertissez ensuite la valeur en une chaîne encodée en Base64.
  stringToSign	Oui	Chaîne à signer. Triez les paramètres devant être signés par ordre alphabétique. Concaténez la clé et la valeur de chaque paramètre à l'aide d'un signe égal (=). Concaténez les paramètres à l'aide d'une esperluette (&). Si vous utilisez le compte Alibaba Cloud auquel appartient l'instance IoT Platform ou un utilisateur RAM auquel les autorisations requises ont été directement accordées au sein de ce compte Alibaba Cloud : Les paramètres devant être signés incluent authId et timestamp. Définissez la valeur au format stringToSign = authId=${accessKey}&timestamp=1573489088171. Si vous utilisez un utilisateur RAM autorisé par un rôle RAM : Les paramètres devant être signés incluent securityToken, authId et timestamp. Définissez la valeur au format stringToSign = authId=${accessKey}&securityToken=${SecurityToken}&timestamp=1573489088171.
  accessSecret	Oui	Si vous utilisez le compte Alibaba Cloud auquel appartient l'instance IoT Platform ou un utilisateur RAM auquel les autorisations requises ont été directement accordées au sein de ce compte Alibaba Cloud : Définissez ce paramètre sur l'AccessKey Secret du compte Alibaba Cloud ou sur l'AccessKey Secret de l'utilisateur RAM. Connectez-vous à la console IoT Platform, placez le curseur sur votre photo de profil, puis cliquez sur AccessKey Management. Sur la page qui s'affiche, récupérez l'AccessKey Secret. Si vous utilisez un utilisateur RAM autorisé par un rôle RAM : Définissez ce paramètre sur l'AccessKey Secret de l'utilisateur RAM qui assume le rôle RAM.

Recevoir les messages envoyés par IoT Platform

Une fois qu'un lien de réception est établi entre un client AMQP et IoT Platform, IoT Platform envoie des messages au client via ce lien.

Chaque message envoyé par IoT Platform au client se compose des éléments suivants :

• Corps du message. La charge utile du message est au format binaire.

• Attributs du message, tels que le sujet (topic) et l'ID du message. Vous pouvez obtenir les attributs à partir de la section application-properties définie dans AMQP. Les attributs sont au format key:value.

  Clé	Description
  topic	Sujet du message.
  messageId	ID du message.
  generateTime	Moment de la génération du message. Remarque Vous ne pouvez pas déterminer l'ordre des messages en vous basant sur le paramètre generateTime.

Accusé de réception du message :

Le client AMQP envoie un accusé de réception à IoT Platform pour notifier la réception d'un message. L'accusé de réception peut être envoyé manuellement ou automatiquement. Nous vous recommandons d'utiliser le mode automatique. Pour plus d'informations, consultez le guide d'utilisation du client.

Exemples

Vous pouvez utiliser l'un des SDK AMQP spécifiques aux langages de programmation suivants pour connecter un client à IoT Platform. Pour plus d'informations sur la configuration des paramètres, consultez la section Paramètres de connexion de cette rubrique.

• Exemple de connexion avec le SDK Java

• Connecter un client à IoT Platform à l'aide du SDK .NET

• Exemple de connexion avec le SDK Node.js

• Connecter un client à IoT Platform à l'aide du SDK Python 2.7

• Exemple : connexion avec le SDK Python 3

• Exemple de connexion avec le SDK PHP

• Exemple de connexion avec le SDK Go

Lors de la connexion d'un client à IoT Platform, vous pouvez recevoir des codes d'erreur liés aux messages. Pour plus d'informations, consultez la section Codes d'erreur liés aux messages de la rubrique « Journaux IoT Platform ».