Cette section explique comment les appareils peuvent utiliser le pont HTTP pour communiquer avec Cloud IoT Core. Pour obtenir des informations générales sur HTTP et MQTT, consultez la section Protocoles.
Pour en savoir plus sur chaque méthode décrite dans cette section, consultez la documentation de l'API.
Avant d'utiliser le pont HTTP, procédez comme suit :
- Configurer un ou plusieurs registres d'appareils, y compris un sujet Cloud Pub/Sub pour les événements de télémétrie
- Créer des appareils
Authentifier les appareils
Chaque requête envoyée au pont HTTP doit inclure un jeton Web JSON (JWT) dans l'en-tête.
curl -H 'authorization: Bearer JWT' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-id}/config?local_version=1'
Le chemin d'accès complet de l'appareil peut se terminer par l'ID ou l'ID numérique de l'appareil. Consultez la section sur l'enregistrement des appareils pour en savoir plus sur les identifiants d'appareil.
Chaque requête doit inclure le jeton JWT, même si vous envoyez plusieurs requêtes à la suite. Cloud IoT Core ne "se souvient" pas de l'authentification via le pont HTTP. Pour en savoir plus sur l'authentification et les jetons JWT, consultez les sections Sécurité de l'appareil et Identifiants de l'appareil.
Publication d'événements de télémétrie
Publiez les événements de télémétrie dans Cloud IoT Core à l'aide de la méthode publishEvent. Les données de charge utile binaire doivent être encodées en base64.
curl -X POST -H 'authorization: Bearer JWT' -H 'content-type: application/json' --data '{"binary_data": "DATA"}' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-id}:publishEvent'
Les événements de télémétrie sont transférés vers un sujet Cloud Pub/Sub, comme spécifié dans Google Cloud Console ou avec le champ eventNotificationConfigs[i].pubsubTopicName dans la ressource de registre d'appareils. La méthode publishEvent fournit un champ subFolder facultatif pour la classification des événements de télémétrie. Pour savoir comment publier des données de sous-dossiers dans des sujets Pub/Sub distincts, consultez la section ci-dessous.
Publier des événements de télémétrie dans des sujets Pub/Sub distincts
Les appareils peuvent publier des données dans des sujets Pub/Sub distincts en spécifiant un sous-dossier dans le champ subFolder de la méthode publishEvent.
curl -X POST -H 'authorization: Bearer JWT' -H 'content-type: application/json' --data '{"binary_data": "DATA", "sub_folder": "SUBFOLDER"}' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-id}:publishEvent'
Ce sous-dossier doit être configuré dans le champ eventNotificationConfigs.subfolderMatches de la ressource de registre d'appareils, avec un sujet Pub/Sub correspondant dans le champ eventNotificationConfigs.pubsubTopicName. Lorsque les données sont envoyées à un sous-dossier, elles sont publiées dans le sous-dossier correspondant au sujet Pub/Sub.
Comme indiqué dans la section Créer un registre d'appareils, tous les registres d'appareils doivent comporter un sujet Pub/Sub par défaut, sans aucun sous-dossier correspondant. Si un sujet Pub/Sub existe par défaut, les appareils y publient automatiquement dans les cas suivants:
- Aucun sous-dossier n'est spécifié dans le champ
subFolder. - Un sous-dossier est spécifié dans le champ
subFolder, mais il n'a pas de sujet Pub/Sub correspondant dans le registre d'appareils.
Dans chacun de ces cas, s'il n'existe aucun sujet Pub/Sub par défaut, les données envoyées depuis l'appareil seront perdues.
Charge excessive et intervalle exponentiel entre les tentatives
Cloud IoT Core limite les projets qui génèrent une charge excessive. Lorsque des appareils effectuent à nouveau des opérations ayant échoué sans attendre, ils peuvent déclencher des limites qui s'appliquent à tous les appareils d'un même projet Google Cloud.
Pour les nouvelles tentatives, nous vous recommandons vivement de mettre en œuvre un algorithme d'intervalle exponentiel entre les tentatives tronqué avec gigue introduite.
Configurer des appareils
Vous pouvez utiliser Cloud IoT Core pour configurer des appareils. La configuration d'un appareil comprend des données binaires qui peuvent être utilisées pour mettre à jour le micrologiciel, redémarrer un appareil, activer une fonctionnalité ou modifier d'autres propriétés.
Pour configurer un appareil à l'aide du pont HTTP, commencez par définir la configuration dans Cloud IoT Core, puis demandez la configuration via l'appareil.
Compression des requêtes HTTP
Un appareil peut envoyer des données compressées avec gzip à Cloud IoT Core via le pont HTTP. Pour envoyer des données compressées à Cloud IoT Core, chaque requête HTTP doit inclure l'en-tête HTTP content-encoding: gzip.
La compression des données vous permet de réduire la bande passante dans la direction de l'appareil au cloud. Cependant, vous ne pouvez pas réduire le coût total de votre utilisation de Cloud IoT Core en compressant les données. Pour en savoir plus, consultez la section Tarifs.
Mise à jour de la configuration de l'appareil...
Lorsqu'il utilise le pont HTTP, l'appareil doit demander explicitement les configurations de l'appareil via l'API. Cloud IoT Core ne transfère pas les configurations vers les appareils via le pont HTTP. À la place, les appareils doivent rechercher de nouvelles configurations.
Pour obtenir la configuration d'appareil actuellement disponible de Cloud IoT Core, utilisez une requête getConfig.
curl -H 'authorization: Bearer JWT' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}/config?local_version=0'
Vous pouvez utiliser le paramètre de requête localVersion pour spécifier la version de configuration actuellement installée sur l'appareil. Le tableau suivant montre l'impact de ce paramètre sur la réponse:
| Version de l'appareil | Réponse de l'API |
|---|---|
localVersion est égal à 0 (valeur par défaut) |
Version la plus récente de Cloud IoT Core |
localVersion est différent de zéro et égal à la version actuellement disponible depuis Cloud IoT Core. |
OK (avec une configuration vide dans le champ binary_data) |
localVersion n'est pas nul et plus ancien (inférieur à) que la version actuellement disponible dans Cloud IoT Core. |
Version actuelle (plus récente) de Cloud IoT Core |
localVersion n'est pas nul et plus récent (supérieur à) que la version actuellement disponible dans Cloud IoT Core. |
Erreur OUT_OF_RANGE |
Définir l'état de l'appareil
Utilisez une requête setState pour signaler l'état de l'appareil à Cloud IoT Core. Les données d'état doivent être encodées en base64.
curl -X POST -H 'authorization: Bearer JWT' -H 'content-type: application/json' --data '{"state": {"binary_data": "DATA"}}' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}:setState'
Pour récupérer les données d'état d'un appareil, affichez les détails de l'appareil dans Cloud Console ou utilisez l'API. Pour en savoir plus, consultez la section État de l'appareil.