Zum Hauptinhalt springen

Veröffentlichung an externe Dienste

Yggio unterstützt das Pushen von Geräte-Update-Daten an externe Dienste.
Es gibt zwei Wege, dies zu erreichen: unseren eigenen internen Publisher und NGSI-Abonnements. Sie funktionieren ähnlich, es gibt jedoch einige wesentliche Unterschiede. Die Hauptunterschiede sind die Unterstützung für MQTT und das Format der veröffentlichten Daten.

NGSI-Abonnements​

Die Dokumentation zu NGSI-Abonnements finden Sie hier

Publisher​

Der Publisher ist ein interner Dienst, der Daten entweder über HTTP oder MQTT sendet.

Um Updates von einer Entität über den Publisher zu erhalten, müssen Sie einen Kanal erstellen. Der Kanal beschreibt, wohin Updates zum Iotnode gesendet werden sollen. Siehe die Abbildung unten.

channel

HTTP-Daten werden über eine POST-Anfrage an die Kanal-URL gesendet.
MQTT-Daten werden über den Yggio-MQTT-Broker an das Kanal-Topic gesendet.

Der Body der Anfrage hat folgendes Format:

{
  iotnode: Iotnode,
  diff: Object,
  event: Object
}

iotnode ist die Iotnode-Entität, die aktualisiert wurde.
diff enthält die Attribute, die bei der Aktualisierung geändert wurden.
event enthält die Attribute, die die Aktualisierung ausgelöst haben.

Einrichten eines Kanals​

Das Erstellen eines Kanals erfolgt über eine einfache POST-Anfrage an unsere REST-API, Details finden Sie auf Swagger.
Die Anforderungen für HTTP- und MQTT-Kanäle unterscheiden sich und sind unten aufgeführt. Kanäle benötigen immer eine iotnodeId und einen name.

HTTP​

Das Erstellen eines HTTP-Kanals erfordert außerdem eine url. Die URL wird in Yggio in keiner Weise verändert, stellen Sie also sicher, dass sie exakt Ihrem Server entspricht. Das bedeutet, dass http/https bei Bedarf enthalten sein muss. Updates für den Iotnode werden per POST mit dem Header Content-Type: application/json; charset=utf-8 an die URL gesendet.

Für HTTP-Kanäle ist ein optionales Feld headers verfügbar – ein JSON-Objekt mit zusätzlichen HTTP-Headern, die in jede Anfrage aufgenommen werden. Zum Beispiel:

{ "X-Api-Key": "my-secret-key" }

Basic Auth ist einfach ein Authorization-Header. Setzen Sie ihn auf Basic <base64>, wobei <base64> in einem Browser btoa("username:password") oder in Node.js Buffer.from("username:password").toString("base64") ist.

Beispiel für die Erstellung eines Kanals mit Basic Auth:

{
  "name": "My secured endpoint",
  "iotnode": "<device-id>",
  "http": {
    "url": "https://my-endpoint.example.com/ingest",
    "headers": { "Authorization": "Basic dXNlcjpwYXNz" }
  }
}

wobei dXNlcjpwYXNz das Ergebnis von btoa("user:pass") ist.

Jeder Authorization-Header ist nur schreibbar – er wird beim Erstellen/Aktualisieren akzeptiert, aber von der API redigiert (nie zurückgegeben).

Bei der Konfiguration eines Kanals in der UI können Sie einen Benutzernamen und ein Passwort im Klartext in die Basic-Auth-Felder eingeben – Yggio kodiert sie vor dem Speichern in den Authorization-Header.

MQTT​

Das Erstellen eines MQTT-Kanals erfordert einen type. Sie können zwischen keycloakUser oder basicCredentialsSet als type wählen. Das Feld recipient gibt den Identifikator der MQTT-Zugangsdaten an, die für den Zugriff auf den Kanal verwendet werden sollen. Wenn der Typ basicCredentialsSet ist, muss recipient die ID des zugehörigen Basic Credentials Set sein. Wenn der Typ keycloakUser ist, muss recipient die Benutzer-ID des Keycloak-Nutzers sein.

Yggio betreibt seinen eigenen Broker und veröffentlicht Iotnode-Updates an benutzer- oder client-spezifische Topics. Es ist weiterhin erforderlich, einen Kanal zu erstellen, um die Updates zu sehen. Informationen zur Verbindung finden Sie unter MQTT (Datenkonsument).