Lektion 2.9 Externe Datenfreigabe

In dieser Lektion untersuchen wir, wie Daten außerhalb der Plattform geteilt werden können. Es gibt drei Hauptmethoden:

1. HTTP Generic Webhooks: Bei einem Update-Ereignis werden die eingehenden Daten, das Delta und die Änderungen an einen angegebenen HTTP-Endpunkt gesendet.
2. MQTT Generic: Daten können auf dem eigenen MQTT-Broker der Plattform veröffentlicht oder umformatiert und über einen MQTT-Connector an einen externen Broker gesendet werden.
3. Dedizierte Connectors: Verwenden Sie einen Connector, um Daten direkt an externe Dienste zu senden, wie Gebäudemanagementsysteme wie Delta Controls EnteliWeb oder Siemens Desigo CC.

In dieser Lektion konzentrieren wir uns auf die ersten beiden Methoden, die direkt innerhalb der Plattform verwendet werden können, ohne Zugriff auf ein externes System zu benötigen.

Um die mit MQTT veröffentlichten Daten zu überwachen, empfehlen wir die Verwendung von MQTT Explorer. Es ist ein leistungsstarkes Tool zum Abonnieren von MQTT-Topics und zum Anzeigen genau der Daten, die veröffentlicht werden, und unter welchem Topic.

MQTT-Datenfreigabe

MQTT ist eine flexible Möglichkeit, Daten zu teilen, und es gibt zwei Hauptmethoden:

1. Auf dem MQTT-Broker der Plattform veröffentlichen mithilfe von Channels, sodass andere Systeme die Daten abonnieren können.
2. Direkt veröffentlichen auf dem MQTT-Broker eines externen Systems.

MQTT-Channels

Beim Erstellen eines MQTT-Channels müssen Sie entscheiden, wie sich Abonnenten authentifizieren. Es gibt zwei Optionen:

• Basic Credential Set: Verwendet einen Benutzernamen und ein Passwort. Dies ist die gängigste und unkomplizierteste Methode.

  Sicherheitstipp: Verwenden Sie ein Passwort mit mindestens 14 gemischten Zeichen.

• API User Token: Verwendet ein Token eines Yggio-API-Benutzers. Tokens laufen periodisch ab und müssen erneuert werden, was für externe Systeme eine Herausforderung sein kann.

  Diese Methode ist die sicherste und folgt dem Standard-OAuth-Flow. Sie wird in der Yggio-UI für Live-Daten über MQTT-WebSockets verwendet.

Ein Basic Credential Set erstellen

Es wird empfohlen, das in der vorherigen Lektion erstellte Basic Credential Set wiederzuverwenden. Wenn Sie keins haben, folgen Sie dieser Anleitung, um ein neues zu erstellen.

1. Öffnen Sie die Swagger-Dokumentation. Klicken Sie auf das Buch-Icon in der Navigationsleiste und dann auf Swagger. Um einen Endpunkt auszuführen, klicken Sie auf Try it out.

2. Authentifizierungsoptionen:

   • Wenn Sie über einen externen IDP angemeldet sind oder MFA aktiviert ist, funktioniert /auth/local nicht. Holen Sie sich stattdessen Ihr Token aus den Entwicklertools Ihres Browsers:
     • Drücken Sie F12, um das Debug-Fenster zu öffnen.
     • Navigieren Sie zu Application → Cookies oder Storage → Cookies.
     • Kopieren Sie Ihr Token und verwenden Sie die Schaltfläche Authorize in Swagger. Fügen Sie das Token in die Eingabeaufforderung ein.
   • Wenn Sie nur ein Passwort haben, gehen Sie zu /auth/local und geben Sie Ihren Benutzernamen und Ihr Passwort in die entsprechenden Felder ein.

3. Führen Sie /users/me aus, um Ihre Authentifizierung zu überprüfen.

4. Gehen Sie zu POST /basic-credentials-sets, ersetzen Sie die Platzhalter für Benutzername und Passwort durch Ihre tatsächlichen Zugangsdaten und klicken Sie auf Execute. Dadurch wird ein Basic Credential Set generiert. Kopieren Sie die zurückgegebene _id aus der Antwort:

{
  "_id": "123456789abcdef",
  "username": "My_basicCredentialsSet_Name"
}

5. Gehen Sie zu dem Gerät, das Sie überwachen möchten, oder wählen Sie mehrere Geräte mit Select Many aus. Öffnen Sie Channels und füllen Sie das Formular aus:
   • Geben Sie dem Channel einen aussagekräftigen Name.
   • Fügen Sie im Feld Recipient die _id Ihres Basic Credential Sets ein (nur Buchstaben und Zahlen verwenden, keine Anführungszeichen).
   • Alle eingehenden Daten von diesen Geräten werden nun auf dem MQTT-Broker der Plattform veröffentlicht, sodass externe Systeme sie abonnieren und empfangen können.

Ihre Channel-Daten überprüfen

Um die auf Ihrem Channel veröffentlichten Daten anzuzeigen, verwenden wir MQTT Explorer.

1. Richten Sie Ihre MQTT-Verbindung in MQTT Explorer ein:
   • Aktualisieren Sie die Plattform-URL, damit sie zu Ihrer Instanz passt.
   • Geben Sie Ihre MQTT-Zugangsdaten ein.
   • Setzen Sie den Port auf 8883 und aktivieren Sie Validate certificate und Encryption.

2. Klicken Sie auf Advanced, entfernen Sie das Standard-Root-Topic (#) und das System-Topic ($SYS#), und fügen Sie dann Ihr spezifisches Topic hinzu. Dies muss getan werden, sonst wird die Plattform Ihre Verbindung ablehnen.

3. Fügen Sie das Topic hinzu, das Sie abonnieren möchten. Es sollte diesem Format folgen: yggio/output/v2/[Ihre Basic Credential Set ID]/iotnode/#

4. Klicken Sie auf Connect. Sie sollten nun Daten sehen, die von der Plattform veröffentlicht werden. Stellen Sie sicher, dass Ihr Gerät einen Uplink erhält, um Daten zu sehen.

Einen MQTT-Connector verwenden, um auf einem externen Dienst zu veröffentlichen

In der vorherigen Lektion 2.8: Connectors haben wir einen MQTT-Connector erstellt, um auf einem externen Dienst zu veröffentlichen, und ihn auf ein eingehendes Topic auf dem MQTT-Broker der Plattform gerichtet.

5. Um die Daten zu überwachen, die Sie über den MQTT-Connector veröffentlichen, konfigurieren Sie MQTT Explorer so, dass er sie abonniert.

• Wenn Sie ein neues basicCredentialSet verwenden, müssen Sie eine neue Verbindung einrichten, indem Sie die obigen Schritte wiederholen.
• Fügen Sie nach korrekten Zugangsdaten Ihr reserviertes Topic aus der vorherigen Lektion hinzu: yggio/generic/v2/[Ihr reserviertes Topic]
• Gehen Sie zurück zum Benutzerhandbuch: MQTT Connector und folgen Sie allen Schritten unter Publishing Data with the Generic MQTT Connector, um eine Regel zum Veröffentlichen von Daten einzurichten.

6. Klicken Sie erneut auf Connect. Sie sehen nun sowohl die Daten, die Sie abonnieren, als auch die Daten, die Sie veröffentlichen.

7. Sobald alles funktioniert, speichern Sie Ihre Verbindung für die zukünftige Verwendung.

Hinweis: Damit dieses Beispiel funktioniert, müssen sowohl veröffentlichte als auch abonnierte Daten dieselben MQTT-Zugangsdaten verwenden.
Wenn Sie unterschiedliche Zugangsdaten verwenden, müssen Sie separate Verbindungen in MQTT Explorer erstellen.

Diese Lektion ist sehr praxisnah, da es viele kommerzielle Szenarien gibt, in denen die Verwendung eines MQTT-Connectors notwendig ist – entweder um Daten an externe Broker zu veröffentlichen oder an ein eingehendes Topic auf dem MQTT-Broker der Plattform.

HTTP-Webhooks-Datenfreigabe

HTTP-Webhooks sind einfacher als MQTT: Erstellen Sie einfach Channels auf dem Gerät und geben Sie das gewünschte Ziel-URL ein. Eventuelle Zugangsdaten oder API-Schlüssel sollten innerhalb der HTTP-URL als Header hinzugefügt werden.

Connectors-Datenfreigabe

Channels können auch Connectors einiger Dienste verwenden; wie der Channel konfiguriert wird, hängt dann vom externen System ab. Zum Beispiel erfordert ein Delta Control Enteliweb-Channel eine BACnet-Konfiguration. Sie sieht typischerweise so aus:

[
  {
    "sourceField": "alarmFloodNumber",
    "deviceNumber": 125,
    "objectType": "binary-value",
    "instance": "810",
    "propertyName": "present-value",
    "createMissing": true,
    "objectName": "Washroom-11223344",
    "priority": "1",
    "dataType": "Boolean"
  }
]

Frage

Wie abonniert man effizient mehrere iotnodes?

Antwort

Verwenden Sie ein Wildcard an der richtigen Stelle im Topic. Wildcards können # für alle oder + sein. Weitere Informationen finden Sie in der MQTT-Spezifikation.

Frage

Kein MQTT-Gerät erscheint in Yggio, wie überprüfe ich, ob mein Topic mit Daten korrekt auf Yggios MQTT-Broker veröffentlicht wurde?

Antwort

Verwenden Sie MQTT Explorer gemäß den obigen Anweisungen, um Topics mit Benutzername und Passwort auf Yggios MQTT-Broker zu abonnieren.