In diesem Abschnitt wird erläutert, wie Geräte über die HTTP-Bridge mit Cloud IoT Core kommunizieren können. Allgemeine Informationen zu HTTP und MQTT finden Sie unter Protokolle.
Ausführliche Informationen zu den in diesem Abschnitt beschriebenen Methoden finden Sie in der API-Dokumentation.
Führen Sie die folgenden Schritte aus, bevor Sie die HTTP-Bridge verwenden:
- Richten Sie ein oder mehrere Geräte-Registries ein, einschließlich eines Cloud Pub/Sub-Themas für Telemetrieereignisse.
- Geräte erstellen
Geräte authentifizieren
Jede Anfrage an die HTTP-Bridge muss ein JSON-Webtoken (JWT) im Header enthalten.
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'
Der vollständige Pfad des Geräts kann in der Geräte-ID oder der numerischen ID des Geräts enden. Weitere Informationen zu Gerätekennungen finden Sie im Abschnitt Geräteregistrierung.
Jede Anfrage muss das JWT enthalten, auch wenn Sie mehrere Anfragen schnell hintereinander senden. Cloud IoT Core speichert keine Authentifizierung über die HTTP-Bridge. Weitere Informationen zur Authentifizierung und zu JWTs finden Sie in den Abschnitten Gerätesicherheit und Geräteanmeldedaten.
Telemetrieereignisse veröffentlichen
Mit der Methode publishEvent können Sie Telemetrieereignisse in Cloud IoT Core veröffentlichen. Binärnutzlastdaten müssen base64-codiert sein.
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'
Telemetrieereignisse werden an ein Cloud Pub/Sub-Thema weitergeleitet, wie in der Google Cloud Console oder mit dem Feld eventNotificationConfigs[i].pubsubTopicName in der Geräte-Registry-Ressource angegeben. Die Methode publishEvent bietet das optionale Feld subFolder zum Klassifizieren von Telemetrieereignissen. Informationen zum Veröffentlichen von Daten aus Unterordnern in separaten Pub/Sub-Themen finden Sie im nächsten Abschnitt.
Telemetrieereignisse in separaten Pub/Sub-Themen veröffentlichen
Geräte können Daten in separaten Pub/Sub-Themen veröffentlichen. Dazu geben Sie in der Methode publishEvent im Feld subFolder einen Unterordner an.
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'
Dieser Unterordner muss im Feld eventNotificationConfigs.subfolderMatches der Registry-Ressource des Geräts mit einem übereinstimmenden Pub/Sub-Thema im Feld eventNotificationConfigs.pubsubTopicName konfiguriert werden. Wenn Daten an einen Unterordner gesendet werden, werden sie im entsprechenden Pub/Sub-Thema des Unterordners veröffentlicht.
Wie unter Geräte-Registry erstellen beschrieben, sollten alle Geräte-Registries ein Pub/Sub-Standardthema ohne übereinstimmenden Unterordner haben. Wenn ein Pub/Sub-Standardthema vorhanden ist, wird es in den folgenden Fällen automatisch veröffentlicht:
- Im Feld
subFolderist kein Unterordner angegeben - Im Feld
subFolderist ein Unterordner angegeben, aber in der Geräte-Registry gibt es kein übereinstimmendes Pub/Sub-Thema
In allen diesen Fällen gehen die vom Gerät gesendeten Daten verloren, wenn kein Pub/Sub-Standardthema vorhanden ist.
Übermäßige Last und exponentieller Backoff
Cloud IoT Core begrenzt Projekte, die eine übermäßige Last generieren. Wenn Geräte fehlgeschlagene Vorgänge wiederholen, ohne zu warten, können sie Limits auslösen, die alle Geräte im selben Google Cloud-Projekt betreffen.
Für Wiederholungsversuche wird dringend empfohlen, einen abgeschnittenen exponentiellen Backoff-Algorithmus mit eingeführtem Jitter zu implementieren.
Geräte konfigurieren
Sie können Cloud IoT Core zum Konfigurieren von Geräten verwenden. Eine Gerätekonfiguration besteht aus Binärdaten, mit denen Firmware aktualisiert, ein Gerät neu gestartet, eine Funktion aktiviert oder andere Eigenschaften geändert werden können.
Wenn Sie ein Gerät mit der HTTP-Bridge konfigurieren möchten, definieren Sie die Konfiguration in Cloud IoT Core und fordern Sie dann die Konfiguration über das Gerät an.
HTTP-Anfragen komprimieren
Ein Gerät kann über die HTTP-Bridge gzip-komprimierte Daten an Cloud IoT Core senden. Zum Senden komprimierter Daten an Cloud IoT Core muss jede HTTP-Anfrage den HTTP-Header content-encoding: gzip enthalten.
Durch die Komprimierung von Daten können Sie die Bandbreite in der Richtung vom Gerät zur Cloud reduzieren. Sie können jedoch die Gesamtkosten Ihrer Cloud IoT Core-Nutzung nicht durch Komprimieren der Daten reduzieren. Weitere Informationen finden Sie unter Preise.
Gerätekonfiguration aktualisieren
Wenn Sie die HTTP-Bridge verwenden, muss das Gerät Gerätekonfigurationen mit der API explizit anfordern. Cloud IoT Core überträgt Konfigurationen nicht über die HTTP-Bridge an Geräte. Stattdessen müssen Geräte neue Konfigurationen abfragen.
Verwenden Sie eine getConfig-Anfrage, um die Gerätekonfiguration abzurufen, die derzeit von Cloud IoT Core verfügbar ist.
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'
Mit dem Abfrageparameter localVersion können Sie die Konfigurationsversion angeben, die sich derzeit auf dem Gerät befindet. Die folgende Tabelle zeigt, wie sich dieser Parameter auf die Antwort auswirkt:
| Geräteversion | API-Antwort |
|---|---|
localVersion ist 0 (Standardwert) |
Neueste Version von Cloud IoT Core |
localVersion ist nicht null und entspricht der Version, die derzeit von Cloud IoT Core verfügbar ist |
OK (mit leerer Konfiguration im Feld binary_data) |
localVersion ist nicht null und älter (niedriger) als die Version, die derzeit in Cloud IoT Core verfügbar ist. |
Aktuelle (neuere) Version von Cloud IoT Core |
localVersion ist nicht null und neuer (höher als) die derzeit von Cloud IoT Core verfügbare Version |
Fehler OUT_OF_RANGE |
Gerätestatus festlegen
Verwenden Sie eine setState-Anfrage, um den Gerätestatus an Cloud IoT Core zu melden. Statusdaten müssen base64-codiert sein.
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'
Wenn Sie Daten zum Gerätestatus abrufen möchten, rufen Sie die Gerätedetails in der Cloud Console auf oder verwenden Sie die API. Weitere Informationen finden Sie im Abschnitt Gerätestatus.