IoT Hub REST

  • Article

Les API REST pour IoT Hub offrent un accès par programmation aux services d’appareil, de messagerie et de travail, ainsi qu’au fournisseur de ressources, dans IoT Hub. Vous pouvez accéder aux services de messagerie à partir d’un service IoT exécuté dans Azure, ou directement sur Internet à partir de toute application pouvant envoyer une requête HTTPS et recevoir une réponse HTTPS.

Service

  • Utilisez cette API pour gérer IoT Hub jumeaux d’appareil. Vous pouvez récupérer et mettre à jour les propriétés du jumeau d’appareil et appeler des méthodes directes sur les appareils.
  • Utilisez ces API pour gérer les identités des appareils dans le registre d’identités d’un hub IoT.
  • Utilisez ces API pour gérer les travaux dans IoT Hub. Vous pouvez planifier, annuler ou obtenir un travail.

Toutes les opérations de tâche sont conformes à la spécification du protocole HTTP/1.1 et chaque opération retourne un x-ms-request-id en-tête qui peut être utilisé pour obtenir des informations sur la demande. Vous devez vous assurer que les demandes adressées à ces ressources sont sécurisées. Pour plus d’informations, consultez IoT Hub Guide du développeur – Sécurité pour plus d’informations sur la création de jetons de sécurité.

Messagerie d’appareil

Utilisez ces API à partir d’un appareil pour envoyer des messages appareil à cloud à un hub IoT et recevoir des messages cloud à appareil à partir d’un hub IoT. Toutes les opérations de tâche sont conformes à la spécification du protocole HTTP/1.1. Vous devez vous assurer que les demandes adressées à ces ressources sont sécurisées. Pour plus d’informations, consultez IoT Hub Guide du développeur - Sécurité pour plus d’informations sur la création de jetons de sécurité.

Fournisseur de ressources

Utilisez ces API pour gérer le déploiement de vos ressources IoT Hub. Pour plus d’informations sur la sécurisation de ces requêtes, consultez Informations de référence sur l’API REST Azure.

Paramètres et en-têtes communs

Les informations suivantes sont communes à toutes les tâches liées à IoT Hub :

  • Remplacez {api-version} par « 2018-06-30 » dans l’URI.

  • Remplacez {subscription-id} par l'identificateur de votre abonnement dans l'URI.

  • Remplacez {resourceGroupName} par le nom du groupe de ressources qui contient (ou contiendra) votre hub IoT.

  • Remplacez {IoTHubName} par le nom de votre hub IoT.

  • Définissez l’en-tête Content-Type sur application/json.

  • Définissez l’en-tête d’autorisation sur un jeton SAP créé comme spécifié dans la section Jetons de sécurité de l’article Utilisation de IoT Hub jetons de sécurité.

  • L’en-tête Etag est retourné dans toutes les requêtes limitées à une seule identité d’appareil, conformément à la RFC7232.

  • Toutes les opérations PUT/PATCH nécessitent que les en-têtes suivants soient spécifiés : If-Match = [*|<etag from get>]

  • Les opérations DELETE peuvent inclure l’en-tête suivant : If-Match = [*|<etag from get>]

Le comportement des ETags peut être vu ci-dessous :

PUT La ressource n’existe pas La ressource existe
If-Match = «  » / absent 201 Créé 200 OK
If-Match = « * » 412 Échec de la condition préalable 200 OK
If-Match = « xyz » 412 Échec de la condition préalable 200 OK / 412 La condition préalable a échoué
If-None-Match = « * » 201 Créé 412 Échec de la condition préalable
Suppression La ressource n’existe pas La ressource existe
If-Match = «  » / absent 204 Pas de contenu 200 OK
If-Match = « * » 204 Pas de contenu 200 OK
If-Match = « xyz » 204 Pas de contenu 200 OK / 412 La condition préalable a échoué

Pour les appels asynchrones :

  • PUT répond avec 201 Créé avec Azure-AsyncOperation'en-tête pour toutes les opérations asynchrones. Toutes les opérations synchrones (mises à jour) retournent 200 OK.

  • DELETE renvoie 202 Accepté avec les en-têtes Location et Retry-After ainsi que Azure-AsyncOperation'en-tête pour les ressources existantes.

  • L’en-tête Location contient l’URL du résultat de l’opération

  • Retry-After-tête contient l’intervalle de nouvelle tentative approprié en secondes

  • Azure-AsyncOperation-tête contient l’URL du résultat de l’opération asynchrone status

  • À l’achèvement, l’URL GET vers l’URL de résultat de l’opération génère exactement le même résultat que si l’opération d’origine s’était terminée de manière synchrone