Ein REST-Sensor holt dir Daten aus praktisch jeder Web-API nach Home Assistant: Blogposts, Statuswerte von eigenen Servern, sogar Vertretungspläne mancher Schulen kommen mittlerweile als JSON. Im Video baue ich so einen Sensor komplett auf, an einem Beispiel mit verschachteltem JSON, und zeige am Ende noch einen Trick für die Fehlersuche. Hier kannst du alles in Ruhe nachlesen.
Erst die API-Antwort lesen, dann YAML schreiben
Der wichtigste Schritt passiert vor der ersten Zeile Konfiguration: Schau dir an, was die API überhaupt zurückliefert. Ruf die URL einfach im Browser auf. Für das Video nutze ich eine Dummy-API, die Blogposts liefert, und deren Antwort sieht gekürzt so aus:
1{
2 "posts": [
3 {
4 "id": 1,
5 "title": "His mother had taught him about plants",
6 "body": "Ein längerer Beschreibungstext...",
7 "tags": ["history", "crime"],
8 "reactions": { "likes": 192, "dislikes": 25 },
9 "views": 305
10 }
11 ],
12 "total": 251
13}Drei Dinge solltest du hier erkennen. Erstens: posts ist ein Array, also eine Liste, das verraten die eckigen Klammern. Zweitens: reactions ist ein eigenes Objekt innerhalb des Posts, die Likes liegen also eine Ebene tiefer. Und drittens: views und likes stehen ohne Anführungszeichen da, das sind echte Zahlen und keine Strings. Mit Zahlen kannst du später direkt rechnen, Strings müsstest du erst umwandeln.
Ob da nun Blogposts drinstehen oder der Stundenplan deines Kindes, ist für die Technik egal. Die Struktur entscheidet, wie dein Template aussehen muss.
Den REST-Sensor mit json_attributes anlegen
Ich lagere meine Sensoren in eine eigene sensor.yaml aus, damit die configuration.yaml nicht endlos lang wird. Wie das Auslagern funktioniert, steht im YAML-Guide. Der Sensor aus dem Video sieht so aus:
1- platform: rest
2 name: Post Details
3 resource: "https://dummyjson.com/posts"
4 json_attributes_path: "$.posts[0]"
5 json_attributes:
6 - title
7 - body
8 - views
9 - reactions
10 value_template: "{{ value_json.posts[0].title }}"
11 scan_interval: 3000Bei resource trägst du den API-Endpunkt ein, also genau die URL, die du dir eben im Browser angeschaut hast. Spannend wird es beim json_attributes_path: Das Dollarzeichen steht für die komplette Antwort, .posts greift auf das Array zu und [0] nimmt das erste Element daraus. Gezählt wird ab null, die 1 wäre also schon der zweite Post. Unter json_attributes listest du dann die Felder auf, die der Sensor als Attribute speichern soll.
Das value_template legt den Hauptwert des Sensors fest, hier der Titel des neuesten Posts. value_json ist dabei die fertig eingelesene Antwort der API. Und das scan_interval bestimmt in Sekunden, wie oft Home Assistant nachfragt. 3000 Sekunden sind 50 Minuten, für einen Blog völlig ausreichend. Zu kleine Werte würde ich lassen: Wer alle 10 Sekunden anklopft, riskiert, dass die API seine IP-Adresse irgendwann blockt.
Nach dem Speichern prüfst du in den Entwicklerwerkzeugen die Konfiguration, lädst die YAML-Konfiguration neu und suchst in den Zuständen nach deinem Sensor. Dort siehst du den Titel als Zustand und darunter alle Attribute.
Verschachtelte Werte mit Template-Sensoren auslesen
Der REST-Sensor sammelt jetzt alles ein, aber für Dashboard-Karten und Automationen willst du meist einzelne Werte als eigene Entität. Dafür legst du Template-Sensoren an, die sich aus den Attributen bedienen:
1- platform: template
2 sensors:
3 post_title:
4 friendly_name: Post Titel
5 value_template: "{{ state_attr('sensor.post_details', 'title') }}"
6 post_likes:
7 friendly_name: Post Likes
8 value_template: "{{ state_attr('sensor.post_details', 'reactions')['likes'] }}"Beim Titel reicht state_attr, das Attribut liegt direkt am Sensor. Bei den Likes kommt die Verschachtelung ins Spiel: reactions ist ja ein Objekt, deshalb hängst du mit ['likes'] noch einen Zugriff hintendran. Genau an dieser Stelle scheitern die meisten Templates, weil der zusätzliche Schritt fehlt.
Danach ist der Rest Routine: Entitäten-Karte aufs Dashboard, post_likes auswählen, fertig. Die komplette Konfiguration zum Kopieren findest du in meinem Snippet zum RESTful Sensor. Und wenn du das Grundprinzip von REST-Sensoren und Webhooks erst mal sortieren willst, schau in die ABC-Folge zu REST und Webhooks.
Template-Fehler finden, wenn die Prüfung nur meckert
Am Ende des Videos baue ich absichtlich Fehler ein: reste statt rest als Plattform, value_jsons statt value_json, ein fehlender Unterstrich im friendly_name. Die Konfigurationsprüfung in den Entwicklerwerkzeugen schlägt dann zwar an, aber die Meldungen sind nicht immer hilfreich, gerade wenn dir die Erfahrung fehlt, sie zu deuten.
Mein Tipp aus dem Video: Kopier das komplette Template und gib es einer KI wie ChatGPT mit der Bitte, die Fehler zu finden. Tippfehler und verrutschte Einrückungen findet sie zuverlässig und liefert dir eine sauber formatierte Datei zurück. Nur bei inhaltlichen Hinweisen musst du selbst denken: In meinem Test wollte ChatGPT den Zugriff auf likes anzweifeln, weil es die API-Antwort nicht kennt. Wir kennen sie aber, also durfte der Hinweis ignoriert werden. Mehr Strategien für solche Fälle habe ich im Troubleshooting-Guide gesammelt.
Häufige Fragen
Was bedeutet json_attributes_path im REST-Sensor?
Das ist der Pfad, an dem Home Assistant die Attribute aus der JSON-Antwort abgreift. Das Dollarzeichen steht für die gesamte Antwort, danach hangelst du dich durch die Struktur: $.posts[0] heißt also "nimm aus der Antwort das Array posts und davon das erste Element". Die Felder aus json_attributes werden dann relativ zu diesem Pfad gelesen.
Warum zeigt mein REST-Sensor unavailable oder unknown an?
Bei "unavailable" war die URL meist nicht erreichbar oder die API liefert einen Fehler, prüfe die Adresse im Browser. "Unknown" deutet auf ein Template-Problem hin: Ein Feldname stimmt nicht exakt mit der Antwort überein oder der Pfad durch das JSON ist falsch. Teste das Template im Template-Tab der Entwicklerwerkzeuge, dort siehst du sofort, was zurückkommt. Denk auch an die Grenze von 255 Zeichen pro Zustand, längere Werte verwirft Home Assistant.
Wie greife ich auf verschachtelte JSON-Werte zu?
Ebene für Ebene. Liegt der Wert in einem Objekt innerhalb der Antwort, hängst du einen weiteren Zugriff an, etwa state_attr('sensor.post_details', 'reactions')['likes']. Bei Arrays wählst du das Element über den Index aus, [0] für das erste. Wichtig: Es wird ab null gezählt.
Welches scan_interval ist sinnvoll?
So groß wie möglich. Der Wert steht in Sekunden, 3000 entspricht 50 Minuten, 43200 wären zwölf Stunden. Überleg dir, wie aktuell die Daten wirklich sein müssen: Ein Blog ändert sich selten im Minutentakt. Sehr kurze Intervalle belasten Home Assistant unnötig, und manche APIs sperren dich bei zu vielen Anfragen aus.
