In diesem Abschnitt wird erläutert, wie Geräte über die MQTT-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. Weitere Informationen finden Sie auch in den MQTT-spezifischen Beispielen.
So veröffentlichen Sie über die MQTT-Bridge:
Installieren Sie auf Ihrem Gerät einen MQTT-Client.
Konfigurieren Sie den MQTT-Client, um das Gerät bei Cloud IoT Core zu authentifizieren.
Starten Sie einen TLS-Handshake über
mqtt.googleapis.com
oder eine langfristige Supportdomain.Veröffentlichen Sie Telemetrieereignisse oder legen Sie den Gerätestatus fest.
MQTT-Server
Cloud IoT Core unterstützt das MQTT-Protokoll durch das Ausführen eines verwalteten Brokers, der den Port mqtt.googleapis.com:8883
überwacht. Port 8883 ist der Standard-TCP-Port, der mit IANA für sichere MQTT-Verbindungen reserviert ist. Verbindungen zu diesem Port müssen TLS-Transport verwenden, das von Open-Source-Clients wie Eclipse Paho unterstützt wird.
Wenn Port 8883 von Ihrer Firewall blockiert wird, können Sie auch Port 443 verwenden: mqtt.googleapis.com:443
.
Dienstqualität (QoS)
Die MQTT-Spezifikation beschreibt drei Dienstqualitätsebenen:
- QoS 0, höchstens einmal bereitgestellt.
- QoS 1, mindestens einmal bereitgestellt.
- QoS 2, genau einmal bereitgestellt.
Cloud IoT Core unterstützt QoS 2 nicht. Wenn Sie QoS 2-Nachrichten veröffentlichen, wird die Verbindung geschlossen. Das Abonnieren eines vordefinierten Themas mit QoS 2 führt zu einem Downgrade der QoS-Ebene auf QoS 1.
QoS 0 und 1 funktionieren in Cloud IoT Core so:
- Eine
PUBLISH
-Nachricht mit QoS 1 wird von der NachrichtPUBACK
bestätigt, nachdem sie erfolgreich an Cloud Pub/Sub gesendet wurde. PUBLISH
-Nachrichten mit QoS 0 erfordern keinePUBACK
-Antworten und können gelöscht werden, wenn der Nachrichtenzustellpfad Jitter aufweist (z. B. wenn Cloud Pub/Sub vorübergehend nicht verfügbar ist).- Die Cloud IoT Core MQTT-Bridge verwaltet einen kleinen Puffer nicht zugestellter Nachrichten, um noch einmal eine Zustellung zu versuchen. Wenn der Puffer voll ist, wird die Nachricht mit QoS 1 gelöscht und es wird keine
PUBACK
-Nachricht an den Client gesendet. Der Client muss die Nachricht noch einmal senden.
Für Gerätekonfigurationen lauten die Dienstqualitätsstufen so:
- Wenn „QoS“ 0 ist, wird eine bestimmte Konfigurationsversion nur einmal auf dem Gerät veröffentlicht. Wenn das Gerät die Konfiguration nicht erhält, muss es noch einmal abonniert werden. Ein Dienstqualitätswert von 0 ist daher nützlich, wenn eine Konfiguration häufig in der Größenordnung von Sekunden oder Minuten aktualisiert werden soll und das Gerät nicht jedes Update erhalten muss.
- Wenn „QoS“ 1 ist, wird das letzte Konfigurationsupdate wiederholt, bis das Gerät es mit einem PUBACK bestätigt. Wenn eine neuere Konfiguration übertragen wird, bevor die ältere bestätigt wurde, wird die ältere nicht noch einmal zugestellt. Stattdessen wird die neue Nachricht zugestellt und noch einmal zugestellt. Diese Ebene ist der sicherste Modus für Gerätekonfigurationen, denn er garantiert, dass das Gerät letztendlich die neueste Konfiguration erhält.
MQTT-Serverzertifikate herunterladen
Für die Verwendung von TLS-Transport müssen Geräte die Cloud IoT Core-Serverzertifikate verifizieren, um sicherzustellen, dass sie mit Cloud IoT Core und nicht mit einer Identitätsübertragung kommunizieren. Die folgenden Zertifikatpakete unterstützen die Verifizierung:
Das vollständige Google-Stamm-CA-Zertifizierungspaket (128 KB) für
mqtt.googleapis.com
.- Dieses Paket baut die Vertrauenskette für die Kommunikation mit Produkten und Diensten von Google auf, einschließlich Cloud IoT Core.
- Geräte mit dem vollständigen Stamm-CA-Zertifizierungspaket kommunizieren direkt mit dem MQTT-Server.
- Dieses Paket wird regelmäßig aktualisiert.
Das minimale Stamm-CA-Set (<1 KB) für
mqtt.2030.ltsapis.goog
. Das minimale Stamm-CA-Set enthält ein primäres Zertifikat und ein Sicherungszertifikat.- Dieses Set ist für Geräte mit Speichereinschränkungen wie Mikrocontroller und stellt eine Vertrauenskette für die Kommunikation mit Cloud IoT Core her.
- Geräte mit dem minimalen Stamm-CA-Set kommunizieren über langfristige Support-Domains mit Cloud IoT Core.
- Dieses Set wird bis 2030 korrigiert (das primäre und das Sicherungszertifikat ändern sich nicht). Für zusätzliche Sicherheit können Sie mit Google Trust Services jederzeit ohne Weiteres zwischen dem primären und dem Sicherungszertifikat wechseln.
Nachdem Sie die Google-Stamm-CA-Zertifikate auf Ihr Gerät heruntergeladen haben, können Sie einen MQTT-Client zur Authentifizierung des Geräts konfigurieren, eine Verbindung zum MQTT-Server herstellen und die Kommunikation über die MQTT-Bridge ausführen.
MQTT-Clients konfigurieren
MQTT-Clients authentifizieren Geräte durch Herstellen einer Verbindung zur MQTT-Bridge. So konfigurieren Sie einen MQTT-Client zur Authentifizierung eines Geräts:
- Legen Sie als MQTT-Client-ID den vollständigen Gerätepfad fest:
projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID
- Verknüpfen Sie den MQTT-Client mit MQTT-Serverzertifikaten.
- Legen Sie den MQTT-Hostnamen auf
mqtt.googleapis.com
oder eine langfristige Supportdomain fest, wenn Sie das minimale Stamm-CA-Set verwendet haben. - Geben Sie einen Nutzernamen an. Die MQTT-Bridge ignoriert das Feld für den Nutzernamen, aber einige MQTT-Clientbibliotheken senden das Passwortfeld nur, wenn das Feld für den Nutzernamen angegeben ist. Die besten Ergebnisse erzielen Sie, wenn Sie einen beliebigen Nutzernamen wie
unused
oderignored
angeben. - Legen Sie das Passwort fest. Das Passwortfeld muss das JWT enthalten.
Im folgenden Beispiel wird gezeigt, wie der MQTT-Client für die Authentifizierung eines Geräts konfiguriert wird:
C++
Die Schritte zum Konfigurieren der Client-ID und zum Authentifizieren eines Geräts sind unten aufgeführt:Java
Node.js
Python
In diesem Beispiel wird die Google API-Clientbibliothek für Python verwendet.Langfristige MQTT-Domain verwenden
Für Domains mit Langzeitsupport (LTS) können Sie eine TLS-Konfiguration für einen längeren Zeitraum verwenden. Sie können einen MQTT-Client einmal einrichten, den MQTT-Client so konfigurieren, dass Nachrichten über eine LTS-Domain veröffentlicht werden, und dann während des unterstützten Zeitraums kontinuierlich über die MQTT-Bridge kommunizieren.
Die aktuell aktive LTS-Domain ist mqtt.2030.ltsapis.goog
. Diese LTS-Domain wird bis 2030 unterstützt.
So verwenden Sie die LTS-Domain:
Konfigurieren Sie einen MQTT-Client für die Veröffentlichung von Nachrichten über eine LTS-Domain.
- Konfigurieren Sie den MQTT-Client, um das Gerät bei Cloud IoT Core zu authentifizieren.
- Verknüpfen Sie beim Konfigurieren des Geräts die primären und Sicherungszertifikate des minimalen Stamm-CA-Sets mit dem MQTT-Client.
Initiieren Sie einen TLS-Handshake über
mqtt.2030.ltsapis.goog
auf Port 8883 oder 443. Verwenden Sie mindestens die folgenden TLS-Funktionen.- TLS 1.2
- P-256 mit SHA-256 als Zertifikatschlüssel und Hash-Algorithmus
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 mit P-256 und unkomprimierten Punkten für die Chiffresammlung.
- Server Name Indication (SNI)
- DNS über TCP oder UDP
Weitere Informationen zum Sichern des MQTT-Traffics, einschließlich der an LTS-Domains gesendeten Nachrichten, finden Sie unter Gerätesicherheitsempfehlungen.
Telemetrieereignisse veröffentlichen
Nachdem das Gerät mit einem MQTT-Client konfiguriert und mit der MQTT-Bridge verbunden ist, kann es ein Telemetrieereignis veröffentlichen. Senden Sie dazu eine PUBLISH
-Nachricht an ein MQTT-Thema im folgenden Format:
/devices/DEVICE_ID/events
Die Geräte-ID ist die String-ID des Geräts, das in der MQTT-Client-ID angegeben ist. Bei der Geräte-ID wird zwischen Groß- und Kleinschreibung unterschieden.
Nachrichten, die in diesem MQTT-Thema veröffentlicht wurden, werden an das Standardtelemetriethema der entsprechenden Registry weitergeleitet. Das Standardtelemetriethema ist das Cloud Pub/Sub-Thema, das in der Registry-Ressource im Feld eventNotificationConfigs[i].pubsubTopicName
angegeben ist.
Wenn kein Pub/Sub-Standardthema vorhanden ist, gehen veröffentlichte Telemetriedaten verloren.
Informationen zum Veröffentlichen von Nachrichten in anderen Cloud Pub/Sub-Themen finden Sie unter Telemetrieereignisse in zusätzlichen Cloud Pub/Sub-Themen veröffentlichen.
Das Feld für die weitergeleiteten Nachrichtendaten enthält eine Kopie der vom Gerät veröffentlichten Nachricht. Jeder Nachricht im Cloud Pub/Sub-Thema werden die folgenden Nachrichtenattribute hinzugefügt:
Attribut | Beschreibung |
---|---|
deviceId |
Die benutzerdefinierte String-ID für das Gerät, z. B. thing1 . Die Geräte-ID muss in der Registry eindeutig sein. |
deviceNumId |
Die vom Server generierte numerische ID des Geräts. Wenn Sie ein Gerät erstellen, generiert Cloud IoT Core automatisch die numerische Geräte-ID. Sie ist global eindeutig und kann nicht bearbeitet werden. |
deviceRegistryLocation |
Die Google Cloud Platform-Region der Geräte-Registry, z. B. us-central1 . |
deviceRegistryId |
Die benutzerdefinierte String-ID für die Geräte-Registry, z. B. registry1 . |
projectId |
Die String-ID des Cloud-Projekts, zu dem die Registry und das Gerät gehören. |
subFolder |
Der Unterordner kann als Ereigniskategorie oder Klassifizierung verwendet werden. Bei MQTT-Clients ist der Unterordner das untergeordnete Thema nach DEVICE_ID/events , das direkt kopiert wird. Wenn der Client beispielsweise im MQTT-Thema /devices/DEVICE_ID/events/alerts veröffentlicht, ist der Unterordner der String alerts . |
Das folgende Beispiel zeigt, wie Sie PUBLISH
-Nachrichten über die MQTT-Verbindung senden:
C++
In diesem Beispiel wird die Google API-Clientbibliothek für Python verwendet.Java
Node.js
Python
In diesem Beispiel wird die Google API-Clientbibliothek für Python verwendet.Telemetrieereignisse in zusätzlichen Cloud Pub/Sub-Themen veröffentlichen
Geräte können Daten in zusätzlichen Cloud Pub/Sub-Themen veröffentlichen. Standardmäßig werden in /devices/DEVICE_ID/events
veröffentlichte MQTT-Nachrichten an das Standardtelemetriethema der entsprechenden Registry weitergeleitet. Sie können im MQTT-Thema einen Unterordner angeben, um Daten an zusätzliche Cloud Pub/Sub-Themen weiterzuleiten.
Der Unterordner ist das untergeordnete Thema nach /devices/DEVICE_ID/events
.
In einem Unterordner veröffentlichte Nachrichten werden an das Cloud Pub/Sub-Thema mit demselben Namen weitergeleitet. Die entsprechende Registry muss mit dem Cloud Pub/Sub-Thema konfiguriert werden. Andernfalls werden Nachrichten an das Standard-Cloud Pub/Sub-Thema weitergeleitet.
In den folgenden Fällen werden Nachrichten an das Cloud Pub/Sub-Standardthema anstelle des zusätzlichen Cloud Pub/Sub-Themas weitergeleitet:
- Im MQTT-Thema ist kein Unterordner angegeben.
- Im MQTT-Thema wird ein Unterordner angegeben, aber in der Geräteregistrierung gibt es kein übereinstimmendes Pub/Sub-Thema.
Wenn das Gerät beispielsweise im MQTT-Thema /devices/DEVICE_ID/events/alerts
veröffentlicht, ist der Unterordner der String alerts
. Nachrichten werden an das zusätzliche Cloud Pub/Sub-Thema weitergeleitet, wenn die beiden Felder eventNotificationConfigs[i].subfolderMatches
und eventNotificationConfigs[i].pubsubTopicName
auf alerts
gesetzt sind. Andernfalls werden Nachrichten an das Cloud Pub/Sub-Standardthema weitergeleitet.
Gerätestatus festlegen
Verbundene Geräte können den Gerätestatus melden, indem sie eine PUBLISH
-Nachricht an das folgende MQTT-Thema senden:
/devices/DEVICE_ID/state
Konfigurieren Sie die Registry mit einem Gerätestatusthema, um Statusnachrichten zu kategorisieren und abzurufen. Das Gerätestatusthema ist das Cloud Pub/Sub-Thema, das im Feld StateNotificationConfig.pubsubTopicName
angegeben ist. Wenn die Registry mit einem Gerätestatusthema konfiguriert ist, werden diese Nachrichten auf Best-Effort-Basis an das entsprechende Cloud Pub/Sub-Thema weitergeleitet.
Weitere Informationen zum Abrufen von Statusnachrichten finden Sie unter Gerätestatus abrufen.
MQTT-Traffic beschränken
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.
Keep-Alive
Wenn Sie die erste MQTT-CONNECT
-Nachricht von einem Client senden, können Sie einen optionalen „Keep-Alive“-Wert angeben. Dieser Wert ist ein Zeitintervall in Sekunden, in dem der Broker erwartet, dass ein Client eine Nachricht sendet, z. B. eine PUBLISH
-Nachricht. Wenn während des Intervalls keine Nachricht vom Client an den Broker gesendet wird, schließt der Broker die Verbindung automatisch. Beachten Sie, dass der von Ihnen angegebene Keep-Alive-Wert mit 1,5 multipliziert wird. Die Festlegung von 10-Minuten-Keep-Alive führt also zu einem Intervall von 15 Minuten.
Weitere Informationen finden Sie in der MQTT-Spezifikation.
Clienteinstellungen
Cloud IoT Core bietet keinen eigenen standardmäßigen Keep-Alive-Wert. Wenn Sie ein Keep-Alive-Intervall angeben möchten, müssen Sie es im Client festlegen.
Die besten Ergebnisse erzielen Sie, wenn Sie das Keep-Alive-Intervall des Clients auf mindestens 60 Sekunden setzen. Viele Open-Source-Clientbibliotheken, einschließlich der Paho MQTT-Bibliotheken für C, Python, Node.js und Java verwenden standardmäßig 60 Sekunden.
Zeitlimit bei Inaktivität
Neben dem Keep-Alive-Intervall hat Cloud IoT Core ein eigenes Zeitlimit von 20 Minuten. Anhand dieses Limits wird eine Clientverbindung automatisch beendet, wenn der Client 20 Minuten lang keine Nachrichten sendet, auch wenn das Keep-Alive-Intervall länger ist. Wenn kein Keep-Alive-Wert angegeben wird, wird die standardmäßige Zeitüberschreitung von 20 Minuten trotzdem wirksam.
Fehlerbehebung
Wenn beim Herstellen der Verbindung Probleme auftreten, finden Sie weitere Informationen unter Fehlerbehebung.