Partager via

Créer et lire des messages IoT Hub

  • Article

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

Remarque

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énements Event Hubs qu’à des messages Service 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éterminé de propriétés système, comme décrit plus loin dans cet article.

  • 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 Guide de protocole MQTT et Guide de protocole AMQP.

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

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.

Remarque

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 au niveau de la destination (par exemple, le format JSON est traité en tant que chaîne analysable à la place de données binaires codées au format Base64), indiquez le type de contenu et le charset appropriés du message.

Pour utiliser le corps de votre message dans une requête de routage IoT Hub, fournissez un objet JSON valide pour le message, puis affectez à la propriété du type de contenu du message la valeur application/json;charset=utf-8.

L’exemple suivant montre un corps de message routable valide :

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

Propriétés système des messages appareil-à-cloud

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, plus - : . + % _ # * ? ! ( ) , = @ ; $ '. 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. 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 appareil-à-cloud

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 non.

{
  "applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
  "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 cloud-à-appareil

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, plus - : . + % _ # * ? ! ( ) , = @ ; $ '. 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 les messages sont générés par IoT Hub, l’ID utilisateur est le nom du hub IoT. 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.

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