Créer et lire des messages IoT Hub

  • Article

Pour prendre en charge l’interopérabilité transparente entre les protocoles, IoT Hub définit un ensemble commun de fonctionnalités de messagerie disponibles dans tous les protocoles orientés appareil. Ceux-ci peuvent être utilisés à la fois dans le routage des messages appareil-à-cloud et dans les messages cloud-à-appareil.

Notes

Certaines des fonctionnalités mentionnées dans cet article, comme la messagerie cloud-à-appareil, les jumeaux d’appareil et la gestion des appareils, sont disponibles uniquement dans le niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.

IoT Hub implémente les messages appareil-à-cloud à l’aide d’un modèle de messagerie en streaming. Les messages appareil-à-cloud d’IoT Hub s’apparentent plus à des événementsEvent Hubs qu’à des messagesService Bus, dans la mesure où de nombreux événements passant à travers le service peuvent être lus par plusieurs lecteurs.

Un message IoT Hub comprend les éléments suivants :

  • Un ensemble prédéfini de propriétés système, telles que répertoriées ci-dessous.

  • Un ensemble de propriétés de l’application. Dictionnaire de propriétés de chaîne que l’application peut définir et auquel elle peut accéder sans avoir à désérialiser le corps du message. IoT Hub ne modifie jamais ces propriétés.

  • Corps d’un message, qui peut être de n’importe quel type de données.

Chaque protocole d’appareil implémente la définition des propriétés de différentes manières. Pour plus d’informations, consultez les guides de développement MQTT et AMQP associés.

Les valeurs et les noms de propriétés peuvent contenir seulement des caractères alphanumériques ASCII, plus les caractères {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} quand vous envoyez des messages appareil-à-cloud avec le protocole HTTPS ou quand vous envoyez des messages cloud-à-appareil.

La messagerie appareil-à-cloud avec IoT Hub présente les caractéristiques suivantes :

  • Les messages appareil-à-cloud sont durables et sont conservés dans le point de terminaison messages/events par défaut d’un hub IoT jusqu’à sept jours.

  • Les messages appareil-à-cloud ne doivent pas dépasser 256 Ko et peuvent être groupés en lots pour optimiser les envois. Les lots ne peuvent pas dépasser 256 Ko.

  • IoT Hub n’autorise pas le partitionnement arbitraire. Les messages appareil-à-cloud sont partitionnés selon leur deviceIdd’origine.

  • Comme expliqué dans Contrôler l’accès à IoT Hub, IoT Hub permet l’authentification et le contrôle d’accès pour chaque appareil.

  • Vous pouvez marquer les messages avec des informations qui sont placées dans les propriétés de l’application. Pour plus d’informations, consultez Enrichissements de messages.

Pour plus d’informations sur l’encodage et le décodage des messages envoyés avec différents protocoles, consultez SDK Azure IoT.

Notes

Chaque protocole IoT Hub fournit une propriété de type de contenu de message qui est respectée lors du routage des données vers des points de terminaison personnalisés. Pour que vos données soient correctement gérées à la destination (par exemple, pour que le JSON soit traité comme une chaîne parsable au lieu de données binaires codées en Base64), vous devez fournir le type de contenu et le jeu de caractères appropriés pour le message.

Pour utiliser le corps de votre message dans une requête de routage IoT Hub, vous devez fournir un objet JSON valide pour le message et définir la propriété de type de contenu du message sur application/json;charset=utf-8.

Un corps de message valide et routable peut ressembler à ce qui suit :

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

Propriétés système des messages IoT Hub D2C

Propriété Description Paramétrable par l'utilisateur ? Mot clé de la
requête de routage
message-id Identificateur correspondant au message défini par l’utilisateur utilisé pour les modèles demande-réponse. Format: Une chaîne qui respecte la casse (jusqu’à 128 caractères) de caractères alphanumériques 7 bits ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. Oui messageId
iothub-enqueuedtime Date et heure de réception du message Appareil-à-cloud par IoT Hub. Non enqueuedTime
user-id Un ID utilisé pour spécifier l’origine des messages. Lorsque des messages sont générés par IoT Hub, la propriété est définie sur {iot hub name}. Oui userId
iothub-connection-device-id Un ID défini par IoT Hub sur les messages appareil vers cloud. Elle contient la propriété deviceId de l’appareil qui a envoyé le message. Non connectionDeviceId
iothub-connection-module-id Un ID défini par IoT Hub sur les messages appareil vers cloud. Il contient la propriété moduleId de l’appareil qui a envoyé le message. Non connectionModuleId
iothub-connection-auth-generation-id Un ID défini par IoT Hub sur les messages appareil vers cloud. Il contient la propriété connectionDeviceGenerationId (conformément aux Propriétés d’identité des appareils) de l’appareil qui a envoyé le message. Non connectionDeviceGenerationId
iothub-connection-auth-method Une méthode d’authentification définie par IoT Hub sur les messages appareil-à-cloud. Cette propriété contient des informations sur la méthode d’authentification utilisée pour authentifier l’appareil qui a envoyé le message. Non connectionAuthMethod
iothub-app-iothub-creation-time-utc Permet à l’appareil d’envoyer l’heure de création de l’événement lors de l’envoi de données dans un lot. Yes creation-time-utc
iothub-creation-time-utc Permet à l’appareil d’envoyer l’heure de création de l’événement lors de l’envoi d’un message à la fois. Yes creation-time-utc
dt-dataschema Cette valeur est définie par IoT Hub sur les messages appareil-à-cloud. Elle contient l’ID du modèle d’appareil défini dans la connexion de l’appareil. Non $dt-dataschema
dt-subject Nom du composant qui envoie les messages appareil-à-cloud. Oui $dt-subject

Propriétés d’application des messages IoT Hub D2C

Une utilisation courante des propriétés d’application consiste à envoyer un horodatage à partir de l’appareil à l’aide de la propriété iothub-creation-time-utc pour enregistrer le moment où le message a été envoyé par l’appareil. Le format de cet horodatage doit être UTC sans informations de fuseau horaire. Par exemple, 2021-04-21T11:30:16Z est valide, 2021-04-21T11:30:16-07:00 ne l’est pas :

{
  "applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
  "messageSource":"telemetry",
  "deviceId":"sample-device-01",
  "schema":"default@v1",
  "templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
  "enqueuedTime":"2021-01-29T16:45:39.143Z",
  "telemetry":{
    "temperature":8.341033560421833
  },
  "messageProperties":{
    "iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
  },
  "enrichments":{}
}

Propriétés système des messages IoT Hub C2D

Propriété Description L’utilisateur est-il définissable ?
message-id Identificateur correspondant au message défini par l’utilisateur utilisé pour les modèles demande-réponse. Format: Une chaîne qui respecte la casse (jusqu’à 128 caractères) de caractères alphanumériques 7 bits ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. Oui
sequence-number Un numéro (unique par file d’attente d’appareil) affecté par IoT Hub à chaque message cloud-à-appareil. Non
to Une destination spécifiée dans les messages cloud vers appareil . Non
absolute-expiry-time Date et heure d’expiration du message. Oui
correlation-id Une propriété de chaîne d’un message de réponse qui contient généralement l'ID du message de la demande dans les modèles demande-réponse. Oui
user-id Un ID utilisé pour spécifier l’origine des messages. Lorsque des messages sont générés par IoT Hub, la propriété est définie sur {iot hub name}. Oui
iothub-ack Un générateur de messages de commentaires. Cette propriété est utilisée dans les messages cloud-à-appareil pour demander à IoT Hub de générer des messages de commentaires à la suite de la consommation du message par l’appareil. Valeurs possibles : none (par défaut) : aucun message de commentaires n’est généré ; positive : recevoir un message de commentaires si le message est achevé ; negative : recevoir un message de commentaires si le message a expiré (ou si le nombre maximal de remises a été atteint) sans être achevé par l’appareil, ou full : propriétés à la fois positive et négative. Oui

Noms des propriétés système

Les noms de propriété système varient en fonction du point de terminaison vers lequel les messages sont acheminés. Pour plus d’informations sur ces noms, consultez le tableau ci-dessous.

Nom de propriété système Event Hubs Stockage Azure Service Bus Event Grid
ID de message message-id messageId MessageId message-id
ID d’utilisateur user-id userId UserId user-id
ID de l’appareil de connexion iothub-connection-device-id connectionDeviceId iothub-connection-device-id iothub-connection-device-id
ID du module de connexion iothub-connection-module-id connectionModuleId iothub-connection-module-id iothub-connection-module-id
ID de génération d’authentification de la connexion iothub-connection-auth-generation-id connectionDeviceGenerationId iothub-connection-auth-generation-id iothub-connection-auth-generation-id
Méthode d’authentification de la connexion iothub-connection-auth-method connectionAuthMethod iothub-connection-auth-method iothub-connection-auth-method
contentType content-type contentType ContentType iothub-content-type
contentEncoding content-encoding contentEncoding ContentEncoding iothub-content-encoding
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime N/A iothub-enqueuedtime
CorrelationId correlation-id correlationId CorrelationId correlation-id
dt-dataschema dt-dataschema dt-dataschema dt-dataschema dt-dataschema
dt-subject dt-subject dt-subject dt-subject dt-subject

Taille des messages

IoT Hub mesure la taille des messages d’une façon indépendante du protocole, en considérant uniquement la charge utile réelle. La taille en octets est calculée comme la somme des valeurs suivantes :

  • La taille du corps en octets.
  • La taille en octets de toutes les valeurs des propriétés système du message.
  • La taille en octets de tous les noms et valeurs des propriétés des utilisateurs.

Les noms et les valeurs des propriétés sont limités aux caractères ASCII ; ainsi, la longueur des chaînes est égale à la taille en octets.

Propriétés de détection d’usurpation d’identité

Pour éviter l’usurpation d’appareil dans les messages appareil-à-cloud, IoT Hub marque tous les messages avec les propriétés suivantes :

  • iothub-connection-device-id
  • iothub-connection-auth-generation-id
  • iothub-connection-auth-method

Les deux premières propriétés contiennent le deviceId et le generationId de l’appareil d’origine, conformément aux Propriétés d’identité des appareils.

La propriété iothub-connection-auth-method contient un objet sérialisé JSON avec les propriétés suivantes :

{
  "scope": "{ hub | device | module }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

Étapes suivantes