Comprendre et appeler des méthodes directes à partir d’IoT Hub

  • Article

Les méthodes directes d’IoT Hub vous permettent d’exécuter à distance des appels sur des appareils à partir du cloud. Les méthodes directes suivent un modèle de requête-réponse et sont destinées aux communications qui nécessitent une confirmation immédiate de leur résultat. Par exemple, le contrôle interactif d’un appareil, tel que la mise en marche d’un ventilateur. Cette fonctionnalité est utile dans les scénarios où le déroulement de l’action immédiate diffère selon que l’appareil a pu répondre ou non.

Remarque

Les fonctionnalités décrites dans cet article sont uniquement disponibles au 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.

Chaque méthode d’appareil cible à un seul appareil. Si vous souhaitez appeler des méthodes directes sur plusieurs appareils, ou planifier des méthodes pour des appareils déconnectés, consultez Planifier des travaux sur plusieurs appareils.

Toute personne disposant d’autorisations Connexion de service sur IoT Hub peut appeler une méthode sur un appareil.

En cas de doute concernant l’utilisation des propriétés souhaitées, des méthodes directes ou des messages cloud-à-appareil, consultez les conseils d’aide sur la communication cloud-à-appareil.

Cycle de vie de méthode

Les méthodes directes sont implémentées sur l’appareil et peuvent nécessiter de zéro à plusieurs entrées dans la charge utile pour s’instancier correctement. Vous appelez une méthode directe via un URI côté service ({iot hub}/twins/{device id}/methods/). Un appareil reçoit des méthodes directes via une rubrique MQTT spécifique de l’appareil ($iothub/methods/POST/{method name}/) ou via des liens AMQP (les propriétés d’application IoThub-methodname et IoThub-status).

Notes

Lorsque vous appelez une méthode directe sur un appareil, les noms et les valeurs de propriété peuvent contenir uniquement des caractères alphanumériques US-ASCII imprimables, à l’exception des caractères suivants : $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT.

Les méthodes directes sont synchrones, et aboutissent ou échouent à l’issue du délai d’expiration. Celui-ci est de 30 secondes par défaut, et peut être défini entre 5 et 300 secondes. Les méthodes directes sont utiles dans des scénarios interactifs où vous souhaitez qu’un appareil agisse si et seulement s’il est en ligne et reçoit des commandes. Par exemple, allumer une lumière à partir d’un téléphone. Dans ces scénarios, vous souhaitez constater immédiatement la réussite ou l’échec de la commande, de façon à ce que le service cloud puisse agir sur le résultat dès que possible. L’appareil peut retourner un corps de message en tant que résultat de l’exécution de la méthode, mais cela n’est pas obligatoire. Il existe ni garantie de classement, ni sémantique de concurrence sur les appels de méthode.

Les méthodes directes sont exclusivement HTTPS côté cloud, et MQTT, AMQP, MQTT sur WebSockets ou AMQP sur WebSockets côté appareil.

La charge utile des requêtes et des réponses de méthodes correspond à un document JSON d’une taille pouvant aller jusqu’à 128 Ko.

Appeler une méthode directe à partir d’une application principale

Pour appeler une méthode directe à partir d’une application back-end, utilisez l’API REST Appeler une méthode d’appareil ou son équivalent dans l’un des kits SDK de service IoT Hub.

Appel de méthode

Les appels de méthode directe sur un appareil sont des appels HTTPS qui comprennent les éléments suivants :

  • l’URI de requête spécifique à l’appareil et la version de l’API :

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • la méthode POST ;

  • des en-têtes contenant l’autorisation, le type de contenu et l’encodage du contenu ;

  • un corps JSON transparent au format suivant :

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

La valeur fournie en tant que responseTimeoutInSeconds dans la requête correspond à la durée pendant laquelle le service IoT Hub doit attendre la fin de l’exécution d’une méthode directe sur un appareil. Définissez ce délai d’expiration de sorte qu’il soit au moins aussi long que la durée d’exécution prévue d’une méthode directe par un appareil. Si le délai d’expiration n’est pas spécifié, la valeur par défaut de 30 secondes est utilisée. Les valeurs minimales et maximales pour responseTimeoutInSeconds sont respectivement 5 et 300 secondes.

La valeur fournie en tant que connectTimeoutInSeconds dans la requête correspond à la durée pendant laquelle le service IoT Hub doit attendre pour qu’un appareil déconnecté soit mis en ligne après l’appel d’une méthode directe. La valeur par défaut est 0, ce qui signifie que les appareils doivent déjà être en ligne lors de l’appel d’une méthode directe. La valeur maximale pour connectTimeoutInSeconds est 300 secondes.

Exemple

Cet exemple lance une requête permettant d’appeler une méthode directe sur un appareil IoT inscrit auprès d’un hub Azure IoT.

Pour commencer, utilisez l’extension Microsoft Azure IoT pour Azure CLI afin de créer une SharedAccessSignature.

az iot hub generate-sas-token -n <iothubName> --du <duration>

Ensuite, remplacez l’en-tête Authorization par la SharedAccessSignature que vous venez de générer, puis modifiez les paramètres iothubName, deviceId, methodName et payload pour qu’ils correspondent à votre implémentation dans l’exemple de commande curl ci-dessous.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

Exécutez la commande modifiée pour appeler la méthode directe spécifiée. Les requêtes réussies retournent un code d’état HTTP 200.

Remarque

L’exemple ci-dessus illustre l’appel d’une méthode directe sur un appareil. Si vous souhaitez appeler une méthode directe dans un module IoT Edge, modifiez la requête de l’URL pour inclure /modules/<moduleName>, comme indiqué ci-dessous :

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

Response

L’application back-end reçoit une réponse constituée des éléments suivants :

  • Code d’état HTTP :

    • 200 indique que l’exécution de la méthode directe est réussie ;
    • 404 indique que l’ID de périphérique n’est pas valide ou que l’appareil n’était pas en ligne lors de l’appel d’une méthode directe et pendant la durée connectTimeoutInSeconds par la suite (utilisez le message d’erreur accompagné pour comprendre la cause racine) ;
    • 504 indique l’expiration du délai de la passerelle provoquée par l’appareil qui ne répond pas à un appel de méthode directe en un temps inférieur ou égal à responseTimeoutInSeconds.

  • des en-têtes contenant l’ID de la requête, le type de contenu et l’encodage du contenu ;

  • un corps JSON au format suivant :

    {
    "status" : 201,
    "payload" : {...}
}

    Les propriétés status et payload sont fournies par l’appareil et permettent de répondre avec le code d’état propre à l’appareil et la réponse de la méthode.

Appel de méthode pour les modules IoT Edge

L’appel de méthodes directes sur un module est pris en charge par l’API REST Appeler une méthode de module ou son équivalent dans l’un des kits SDK de service IoT Hub.

Le moduleId est transmis avec le deviceId dans l’URI de requête lors de l’utilisation de l’API REST ou en tant que paramètre lors de l’utilisation d’un kit SDK de service. Par exemple : https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Le corps de la requête et la réponse sont similaires à ceux des méthodes directes appelées sur l’appareil.

Gérer une méthode directe sur un appareil

Sur un appareil IoT, les méthodes directes peuvent être reçues via MQTT, AMQP ou l’un de ces protocoles via WebSockets. Les kits SDK des appareils IoT Hub vous permettent de recevoir et de répondre à des méthodes directes sur des appareils sans avoir à vous soucier des détails du protocole sous-jacent.

MQTT

La section suivante s’applique au protocole MQTT. Pour en savoir plus sur l’utilisation directe du protocole MQTT avec IoT Hub, consultez Prise en charge du protocole MQTT.

Appel de méthode

Les appareils reçoivent des requêtes de méthode directe sur la rubrique MQTT : $iothub/methods/POST/{method name}/?$rid={request id}. Toutefois, le request id est généré par IoT Hub et ne peut pas être connu à l’avance. Vous devez donc vous abonner à $iothub/methods/POST/#, puis filtrer les messages remis en fonction des noms de méthode pris en charge par votre appareil. (Vous utiliserez le request id pour répondre.)

Le corps que l’appareil reçoit est au format suivant :

{
    "input1": "someInput",
    "input2": "anotherInput"
}

Les demandes de méthode sont QoS 0.

response

L’appareil envoie des réponses à $iothub/methods/res/{status}/?$rid={request id}, où :

  • La propriété status est l’état d’exécution de la méthode fourni par l’appareil.

  • La propriété $ridest l’ID de demande de l’appel de méthode reçu d’IoT Hub. L’ID de requête est une valeur au format hexadécimal.

Le corps est défini par l’appareil et peut être n’importe quel état.

AMQP

La section suivante s’applique au protocole AMQP. Pour en savoir plus sur l’utilisation directe du protocole AMQP avec IoT Hub, consultez Prise en charge du protocole AMQP.

Appel de méthode

L’appareil reçoit des requêtes de méthode directe en créant un lien de réception à l’adresse amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Le message AMQP est transmis au lien de réception qui représente la demande de méthode. Il contient les sections suivantes :

  • La propriété d’ID de corrélation, qui contient un ID de requête qui doit être transmis avec la réponse de la méthode correspondante.

  • Une propriété d’application nommée IoThub-methodname, qui contient le nom de la méthode appelée.

  • Le corps du message AMQP, qui contient la charge utile de la méthode en tant que JSON.

response

L’appareil crée un lien d’envoi pour retourner la réponse de la méthode à l’adresse amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

La réponse de la méthode est retournée via le lien d’envoi et est structurée comme suit :

  • La propriété d’ID de corrélation, qui contient l’ID de requête transmis dans le message de requête de la méthode.

  • Une propriété d’application nommée IoThub-status, qui contient l’état de la méthode fournie par l’utilisateur.

  • Le corps du message AMQP, qui contient la réponse de la méthode en tant que JSON.

Étapes suivantes

À présent que vous savez comment utiliser les méthodes directes, vous serez peut-être intéressé par l’article suivant du Guide du développeur IoT Hub :