Zugriff auf die API & den MQTT-Broker der IoT-Plattform

Die IoT-Plattform bietet zwei programmatische Schnittstellen:

• eine REST-API (https://staging.yggio.net/api/…), vollständig dokumentiert in Swagger; und
• einen MQTT-Broker (mqtt.staging.yggio.net:8883) für Pub/Sub - siehe die MQTT-Referenz für alle Details.

Diese Seite ist eine Kurzreferenz für den Zugriff mit drei gängigen Werkzeugen - curl, Postman und MQTT Explorer. Für praktische Anleitungen siehe die Schulungslektionen: Curl, Postman, MQTT Explorer.

Authentifizierung (REST)

Holen Sie sich ein Benutzer-Zugriffstoken und übergeben Sie es als Bearer-Header bei jeder authentifizierten Anfrage.

POST https://staging.yggio.net/api/auth/local
Content-Type: application/json

{ "username": "…", "password": "…" }      →   { "token": "eyJ…" }

Authorization: Bearer <token>

Tokens laufen ab; fordern Sie bei Bedarf ein neues an. Für langlebigen Anwendungszugriff erstellen Sie eine Client-App (POST /api/client-apps) oder, für MQTT, ein Basic Credential Set (POST /api/basic-credentials-sets). Der Daten-Push-Endpunkt des Geräts (/http-push/generic) authentifiziert sich stattdessen mit dem eigenen secret des Geräts.

Gängige REST-Endpunkte

Operation	Anfrage
Geräte auflisten	GET /api/iotnodes (Filter: ?q=<field>)
Ein Gerät	GET /api/iotnodes/{_id}
Ein Gerätefeld aktualisieren	PUT /api/iotnodes/{_id}
Zeitreihe	GET /api/iotnodes/{_id}/stats?measurement=<field>&start=<ms>&distance=<s>
Daten an ein generisches Gerät senden	POST /http-push/generic?identifier=secret (Body enthält secret)

Siehe Swagger für die vollständige Liste und Schemas.

curl

Kommandozeile, ideal zum Skripten. Halten Sie das Token in einer Variable:

export YGGIO_URL="staging.yggio.net"
export YGGIO_TOKEN=$(curl -sS -X POST "https://$YGGIO_URL/api/auth/local" \
  -H "Content-Type: application/json" \
  -d '{"username":"USER","password":"PASS"}' | jq -r .token)

# lesen
curl -sS "https://$YGGIO_URL/api/iotnodes?q=temperature" \
  -H "Authorization: Bearer $YGGIO_TOKEN" | jq .

# an ein generisches Gerät senden (verwendet das Geräte-Secret, nicht das Token)
curl -sS "https://$YGGIO_URL/http-push/generic?identifier=secret" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOURDEVICESECRET","temperature":22}'

Postman

GUI-HTTP-Client; gut zum Erkunden der API und zum Ausführen gespeicherter Collections.

1. Erstellen Sie eine POST-Anfrage {{baseUrl}}/api/auth/local (JSON-Body mit username/password); speichern Sie im Tests-Tab das Token mit pm.environment.set("token", pm.response.json().token).
2. Setzen Sie bei anderen Anfragen den Header Authorization: Bearer {{token}}.
3. Lesen mit GET {{baseUrl}}/api/iotnodes; senden mit POST {{baseUrl}}/http-push/generic?identifier=secret.
4. Für den Massenimport von Zeitreihen gibt es eine fertige Collection - CSV-Import-Collection (siehe Lektion 1.4).

MQTT-Broker

Verbinden Sie sich mit einem beliebigen MQTT-Client:

Einstellung	Wert
Host	mqtt.staging.yggio.net
Port	8883 (TLS - Verschlüsselung + Zertifikatsprüfung aktivieren)
Zugangsdaten	ein Basic Credential Set
Veröffentlichen unter (generisches Gerät)	yggio/generic/v2/<id>
Ausgabe des Nutzers abonnieren	yggio/output/v2/<userID>/#

Das Veröffentlichen unter yggio/generic/v2/<id> erstellt/aktualisiert automatisch ein Gerät; Subtopics werden zu verschachtelten Objekten. Alle Details (Kanäle, reservierte Topics, Beispiele) finden Sie in der MQTT-Referenz.

MQTT Explorer

MQTT Explorer ist ein Desktop-Client zur Inspektion des Brokers:

1. Neue Verbindung → Host mqtt.staging.yggio.net, Port 8883, Verschlüsselung an, Zertifikat validieren an, und Ihr Basic Credential Set.
2. Entfernen Sie zuerst die Standard-Topics. MQTT Explorer abonniert standardmäßig # und $SYS/#, aber die IoT-Plattform gewährt keinen Zugriff auf die Wurzel des Brokers - diese Abonnements werden abgelehnt (sie benötigen Root-Rechte). Öffnen Sie Advanced, löschen Sie die Einträge # und $SYS/# und fügen Sie stattdessen Ihr eigenes Topic hinzu (z. B. Ihr Geräte- oder Nutzer-Ausgabe-Topic). Das ist der häufigste Fehler.
3. Veröffentlichen Sie eine JSON-Payload unter yggio/generic/v2/<id>, um ein Gerät zu erstellen/aktualisieren.
4. Abonnieren Sie Ihr eigenes Topic, um live genau zu beobachten, was die IoT-Plattform veröffentlicht.

Werkzeug-Übersicht

Werkzeug	Schnittstelle	Am besten für
curl	REST	schnelle Tests, Skripting/Automatisierung
Postman	REST	Erkunden der API, gespeicherte Collections, CSV-Import
MQTT Explorer	MQTT	Testdaten veröffentlichen, den Broker inspizieren
mosquitto_sub/pub	MQTT	CLI-/skriptbasiertes MQTT (siehe MQTT-Referenz)

Siehe auch

• MQTT-Referenz - der Broker im Detail (Kanäle, reservierte Topics, Authentifizierung).
• Translator API - das Übersetzer-Objekt und das Datenmodell.
• Swagger - die vollständige REST-API-Referenz.
• Schulung: Curl, Postman, MQTT Explorer.