Partager via

Référence de l’API MQTT 5 du plan de données IoT Hub (déconseillée)

  • Article

Ce document définit les opérations disponibles dans la version 2.0 (api-version : 2020-10-01-preview) de l’API du plan de données IoT Hub.

Remarque

La prise en charge de MQTT 5 dans IoT Hub a été mise hors service et IoT Hub n’offre qu’une prise en charge limitée de MQTT. Si votre solution a besoin d’une prise en charge de MQTT v3.1.1 ou v5, nous vous recommandons la prise en charge de MQTT dans Azure Event Grid. Pour plus d’informations, consultez l’article Comparer la prise en charge de MQTT dans IoT Hub et Event Grid.

Opérations

Obtenir un jumeau

Obtenir l’état du jumeau

Requête

Nom de la rubrique : $iothub/twin/get

Propriétés : aucune

Charge utile : vide

Réponse en cas de réussite

Propriétés : aucune

Charge utile : Jumeau

Autres réponses

État Name Description
0100 Demande incorrecte Le message d’opération est malformé et ne peut pas être traité.
0101 Non autorisé Le client n’est pas autorisé à effectuer l’opération.
0102 Non autorisée L’opération n’est pas autorisée.
0501 Throttled Le taux de requêtes est trop élevé par SKU.
0502 Quota dépassé Le quota quotidien par SKU actuel est dépassé.
0601 Erreur de serveur Erreur interne du serveur.
0602 Délai d'expiration L’opération a expiré avant d’être terminée.
0603 Serveur occupé Le serveur est occupé.

Exemple de pseudo-code


-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Jumeau patch signalé

État signalé du jumeau patch

Requête

Nom de la rubrique : $iothub/twin/patch/reported

Propriétés :

Name Type Requise Description
if-version u64 Non

Charge utile : TwinState

Réponse en cas de réussite

Propriétés :

Name Type Requise Description
version u64 Oui Version de l’état signalé après l’application du patch

Charge utile : vide

Autres réponses

État Name Description
0104 Échec de la précondition la condition préalable n’a pas été remplie, entraînant l’annulation de la requête
0100 Demande incorrecte Le message d’opération est malformé et ne peut pas être traité.
0101 Non autorisé Le client n’est pas autorisé à effectuer l’opération.
0102 Non autorisée L’opération n’est pas autorisée.
0501 Throttled Le taux de requêtes est trop élevé par SKU.
0502 Quota dépassé Le quota quotidien par SKU actuel est dépassé.
0601 Erreur de serveur Erreur interne du serveur.
0602 Délai d'expiration L’opération a expiré avant d’être terminée.
0603 Serveur occupé Le serveur est occupé.

Exemple de pseudo-code


-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/reported
    [if-version: <u64>]
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Recevoir des commandes

Recevoir et gérer des commandes

Message

Nom de la rubrique : $iothub/commands

Propriétés :

Name Type Requise Description
sequence-no u64 Oui Numéro de séquence du message.
enqueued-time time Oui Horodatage du moment où le message est entré dans le système.
delivery-count u32 Oui Nombre de tentatives de remise du message.
creation-time time Non Horodatage du moment où le message a été créé (fourni par l’expéditeur).
message-id string non Identité du message (fournie par l’expéditeur).
user-id string non Identité de l’utilisateur (fournie par l’expéditeur).
correlation-id string non Identité de la corrélation (fournie par l’expéditeur).
Type de contenu string non Détermine le type de contenu de la charge utile.
content-encoding string non Détermine l’encodage du contenu de la charge utile.

Charge utile : n’importe quelle séquence d’octets

Accusé de réception en cas de réussite

Indique que la commande a été acceptée pour être traitée par le client

Propriétés : aucune

Charge utile : vide

Autres accusés de réception

Code de raison État Name Description
131 0603 Arrêter Indique que la commande ne sera pas traitée pour l’instant et qu’elle devra être à nouveau livrée plus tard.
131 0100 Rejeter Indique que le client a rejeté la commande et qu’elle ne doit pas être tentée à nouveau.

Exemple de pseudo-code


-> SUBSCRIBE
    - Topic: $iothub/commands
      QoS: 1
<- PUBLISH
    QoS: 1
    Topic: $iothub/commands
    sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
    Payload: ...

-> PUBACK

Recevoir des méthodes directes

Recevoir et gérer les appels de méthode directe

Requête

Nom de la rubrique : $iothub/methods/{name}

Propriétés : aucune

Charge utile : n’importe quelle séquence d’octets

Réponse en cas de réussite

Propriétés :

Name Type Requise Description
response-code u32 Oui

Charge utile : n’importe quelle séquence d’octets

Autres réponses

État Name Description
06A0 Indisponible Indique que le client n’est pas joignable via cette connexion.

Exemple de pseudo-code


-> SUBSCRIBE
    - Topic: methods/{name}
      QoS: 0
<- SUBACK
<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/{name}
-> PUBLISH
    QoS: 0
    Topic: $iothub/responses

Recevoir les modifications d’état souhaité du jumeau

Recevoir les mises à jour de l’état souhaité du jumeau

Message

Nom de la rubrique : $iothub/twin/patch/desired

Propriétés :

Name Type Requise Description
version u64 Oui Version de l’état souhaité correspondant à cette mise à jour

Charge utile : TwinState

Exemple de pseudo-code


-> SUBSCRIBE
    - Topic: $iothub/twin/patch/desired
      QoS: 0
<- PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/desired
    version: <u64>
    Payload: ...

Envoyer des données de télémétrie

Publiez le message sur le canal de télémétrie - Event Hubs par défaut ou sur un autre point de terminaison via la configuration du routage.

Message

Nom de la rubrique : $iothub/telemetry

Propriétés :

Name Type Requise Description
Type de contenu string non se traduit en propriété système content-type sur le message publié
content-encoding string non se traduit en propriété système content-encoding sur le message publié
message-id string non se traduit en propriété système message-id sur le message publié
user-id string non se traduit en propriété système user-id sur le message publié
correlation-id string non se traduit en propriété système correlation-id sur le message publié
creation-time time Non se traduit en propriété iothub-creation-time-utc sur le message publié

Conseil

Le format de creation-time 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.

Charge utile : n’importe quelle séquence d’octets

Accusé de réception en cas de réussite

Le message a été correctement publié sur le canal de télémétrie.

Propriétés : aucune

Charge utile : vide

Autres accusés de réception

Code de raison État Name Description
131 0100 Demande incorrecte Le message d’opération est malformé et ne peut pas être traité.
135 0101 Non autorisé Le client n’est pas autorisé à effectuer l’opération.
131 0102 Non autorisée L’opération n’est pas autorisée.
131 0601 Erreur de serveur Erreur interne du serveur.
151 0501 Throttled Le taux de requêtes est trop élevé par SKU.
151 0502 Quota dépassé Le quota quotidien par SKU actuel est dépassé.
131 0602 Délai d'expiration L’opération a expiré avant d’être terminée.
131 0603 Serveur occupé Le serveur est occupé.

Exemple de pseudo-code

-> PUBLISH
    QoS: 1
    Topic: $iothub/telemetry
    [Content Type: <string>]
    [content-encoding: <string>]
    [message-id: <string>]
    [user-id: <string>]
    [correlation-id: <string>]
    [creation-time: <time>]

<- PUBACK

Réponses

Demande incorrecte

Le message d’opération est malformé et ne peut pas être traité.

Code motif : 131

État : 0100

Propriétés :

Name Type Requise Description
reason string non contient des informations spécifiques sur ce qui n’est pas valide dans le message

Charge utile : vide

Conflit

L’opération est en conflit avec une autre opération en cours.

Code motif : 131

État : 0103

Propriétés :

Name Type Requise Description
trace-id string non ID de trace pour la corrélation avec d’autres diagnostics de l’erreur
reason string non contient des informations spécifiques sur ce qui n’est pas valide dans le message

Charge utile : vide

Non autorisée

L’opération n’est pas autorisée.

Code motif : 131

État : 0102

Propriétés :

Name Type Requise Description
reason string non contient des informations spécifiques sur ce qui n’est pas valide dans le message

Charge utile : vide

Non autorisé

Le client n’est pas autorisé à effectuer l’opération.

Code motif : 135

État : 0101

Propriétés :

Name Type Requise Description
trace-id string non ID de trace pour la corrélation avec d’autres diagnostics de l’erreur

Charge utile : vide

Introuvable

la ressource demandée n’existe pas

Code motif : 131

État : 0504

Propriétés :

Name Type Requise Description
reason string non contient des informations spécifiques sur ce qui n’est pas valide dans le message

Charge utile : vide

Non modifié

La ressource n’a pas été modifiée selon la condition préalable indiquée.

Code motif : 0

État : 0001

Propriétés : aucune

Charge utile : vide

Échec de la précondition

La condition préalable n’a pas été remplie, entraînant l’annulation de la requête

Code motif : 131

État : 0104

Propriétés : aucune

Charge utile : vide

Quota dépassé

Le quota quotidien par SKU actuel est dépassé.

Code motif : 151

État : 0502

Propriétés : aucune

Charge utile : vide

Ressource épuisée

La ressource n’a pas la capacité nécessaire pour terminer l’opération.

Code motif : 131

État : 0503

Propriétés :

Name Type Requise Description
reason string non contient des informations spécifiques sur ce qui n’est pas valide dans le message

Charge utile : vide

Serveur occupé

Le serveur est occupé.

Code motif : 131

État : 0603

Propriétés :

Name Type Requise Description
trace-id string non ID de trace pour la corrélation avec d’autres diagnostics de l’erreur

Charge utile : vide

Erreur de serveur

Erreur interne du serveur.

Code motif : 131

État : 0601

Propriétés :

Name Type Requise Description
trace-id string non ID de trace pour la corrélation avec d’autres diagnostics de l’erreur

Charge utile : vide

Échec de la cible

La cible a répondu, mais la réponse est non valide ou malformée.

Code motif : 131

État : 06A2

Propriétés :

Name Type Requise Description
reason string non contient des informations spécifiques sur ce qui n’est pas valide dans le message

Charge utile : vide

Expiration du délai d’attente du ticket

Expiration du délai d’attente dont dispose la cible pour terminer la requête

Code motif : 131

État : 06A1

Propriétés :

Name Type Requise Description
trace-id string non ID de trace pour la corrélation avec d’autres diagnostics de l’erreur
reason string non contient des informations spécifiques sur ce qui n’est pas valide dans le message

Charge utile : vide

Cible non disponible

La cible est inaccessible pour terminer la requête.

Code motif : 131

État : 06A0

Propriétés : aucune

Charge utile : vide

Throttled

Le taux de requêtes est trop élevé par SKU.

Code motif : 151

État : 0501

Propriétés : aucune

Charge utile : vide

Délai d'expiration

L’opération a expiré avant d’être terminée.

Code motif : 131

État : 0602

Propriétés :

Name Type Requise Description
trace-id string non ID de trace pour la corrélation avec d’autres diagnostics de l’erreur

Charge utile : vide