Zum Hauptinhalt springen

Lektion 3.6 Curl

curl führt dieselben REST-API-Aufrufe der IoT-Plattform aus wie Postman, jedoch direkt über die Kommandozeile – ideal für schnelle Tests und für Skripting oder Automatisierung. Diese Lektion spiegelt die Postman-Lektion mit curl.

Die Beispiele verwenden zwei Shell-Variablen, damit Sie sich nicht wiederholen müssen:

export YGGIO_URL="staging.yggio.net"

Übung 1 – Ein Access Token erhalten​

curl -sS -X POST "https://$YGGIO_URL/api/auth/local" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

Die Antwort ist { "token": "eyJ..." }. Erfassen Sie sie in einer Variable (mit jq):

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

Alle authentifizierten Aufrufe verwenden dann den Header Authorization: Bearer $YGGIO_TOKEN.

Übung 2 – Ihre Geräte auflisten​

curl -sS "https://$YGGIO_URL/api/iotnodes" \
  -H "Authorization: Bearer $YGGIO_TOKEN" | jq .

Filtern Sie auf Geräte mit einem Feld, z. B. temperature:

curl -sS "https://$YGGIO_URL/api/iotnodes?q=temperature" \
  -H "Authorization: Bearer $YGGIO_TOKEN" | jq '.[].name'

Übung 3 – Einen Wert an ein generisches Gerät pushen​

Erstellen Sie zuerst ein Generic-Gerät mit einem secret (siehe Lektion 2.3). Dieser Endpunkt authentifiziert über das Geräte-secret, nicht über den Bearer-Token:

curl -sS "https://$YGGIO_URL/http-push/generic?identifier=secret" \
  -H "Content-Type: application/json" \
  -d '{
        "secret": "YOURDEVICESECRET",
        "temperature": 22,
        "relativeHumidity": 48
      }'

Das Gerät aktualisiert sich in der IoT-Plattform.

Übung 4 – Ein Gerät aktualisieren (Feld hinzufügen / entfernen)​

Verwenden Sie PUT /api/iotnodes/{_id} mit dem Bearer-Token, um z. B. ein temporäres secret hinzuzufügen (wie beim CSV-Zeitreihenimport verwendet) und es später wieder zu entfernen:

# ein secret hinzufügen
curl -sS -X PUT "https://$YGGIO_URL/api/iotnodes/DEVICE_ID" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret":"TEMP_SECRET"}'

# es wieder entfernen
curl -sS -X PUT "https://$YGGIO_URL/api/iotnodes/DEVICE_ID" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret":"$unset"}'

Tipp: Leiten Sie Antworten durch jq, um lesbares JSON zu erhalten, und bewahren Sie Ihren Token in einer Umgebungsvariable auf, statt ihn in jeden Befehl einzufügen.

Was Sie gelernt haben​

  • Wie man ein Token erhält (POST /api/auth/local) und es als Authorization: Bearer übergibt.
  • Wie man liest (GET /api/iotnodes), pusht (POST /http-push/generic) und aktualisiert (PUT /api/iotnodes/{_id}) über die Kommandozeile.
  • Wie man diese Aufrufe mit Shell-Variablen und jq skriptet.

Wie geht es weiter​

  • Lektion 3.5 Postman – dieselben Aufrufe in einer GUI.
  • Swagger (https://staging.yggio.net/swagger) – die vollständige API-Referenz.
  • Nächste Lektion: Übersetzerentwicklung – die fortgeschrittenste Lektion.