Home Assistant per REST-API anbinden
Home Assistant gezielt per HTTP ansprechen
Die REST-API eignet sich für einzelne Abfragen und Aktionen: Ein Skript liest einen Zustand, löst eine Home-Assistant-Aktion aus oder legt vorübergehend einen Zustand im State Machine an. Anders als MQTT Discovery registriert POST /api/states/... keine dauerhaft verwaltete Integration.
1. Token mit Bedacht erstellen
Ein Long-Lived Access Token wird im Home-Assistant-Benutzerprofil erzeugt und nur einmal angezeigt. Dafür sollte ein eigener, möglichst wenig privilegierter Home-Assistant-Benutzer verwendet werden. Das Token gehört in eine Datei mit restriktiven Rechten oder in die Credential-Verwaltung des Dienstes, nie in Quellcode oder öffentliche Beispiele.
2. Verbindung testen
curl --fail --show-error \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
http://IP-DER-HA-INSTANZ:8123/api/
Unverschlüsseltes HTTP ist nur in einem vertrauenswürdigen, nicht mitgelesenen LAN vertretbar. Über WLAN-Gastnetze, das Internet oder andere fremde Netze wird HTTPS beziehungsweise ein VPN verwendet. Port 8123 sollte nicht allein für dieses Skript direkt ins Internet weitergeleitet werden.
3. Python-Client mit Fehlerprüfung
import os
import requests
HA_URL = "http://IP-DER-HA-INSTANZ:8123"
TOKEN = os.environ["HA_TOKEN"]
HEADERS = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json",
}
def ha_request(method, path, **kwargs):
response = requests.request(
method,
f"{HA_URL}{path}",
headers=HEADERS,
timeout=(5, 15),
**kwargs,
)
response.raise_for_status()
return response
Ein Zeitlimit verhindert, dass ein Netzfehler den Dienst unbegrenzt blockiert. raise_for_status() macht Authentifizierungs- und Serverfehler sichtbar.
4. Zustand lesen
response = ha_request("GET", "/api/states/sensor.aussentemperatur")
data = response.json()
print(data["state"])
Home-Assistant-Zustände sind Zeichenketten. Vor Berechnungen müssen unknown, unavailable und unerwartete Einheiten behandelt werden.
5. Zustand in die State Machine schreiben
payload = {
"state": "42.5",
"attributes": {
"friendly_name": "LAN-Server Auslastung",
"unit_of_measurement": "%",
},
}
ha_request("POST", "/api/states/sensor.lanserver_auslastung", json=payload)
Der Endpunkt setzt eine Zustandsrepräsentation. Er erstellt keine Integration und keinen Sensor mit eigenem Datenabruf. Nach einem Neustart muss der Wert erneut geschrieben werden. Für dauerhaft verwaltete, regelmäßig aktualisierte Sensoren ist MQTT Discovery meist passender.
6. Eine Aktion auslösen
payload = {"entity_id": "light.wohnzimmer"}
ha_request("POST", "/api/services/light/turn_on", json=payload)
Entitäts-ID und Payload müssen fest vorgegeben oder streng validiert sein. Ungeprüfte Benutzereingaben dürfen nicht zu beliebigen Service-Aufrufen werden.
Fehlersuche
401 Unauthorized: Token, Benutzerstatus und Authorization-Header prüfen.404 Not Found: Pfad oder Entity-ID kontrollieren.- Zeitüberschreitung: Routing, Firewall, DNS und HA-Erreichbarkeit prüfen.
- TLS-Fehler: Zertifikatskette und Hostname korrigieren; Zertifikatsprüfung nicht dauerhaft abschalten.
- Unerwartete Werte: HTTP-Antwort und JSON-Struktur protokollieren, aber Token aus Logs entfernen.
Fazit
REST ist der direkte Weg für einzelne Lese- und Aktionsaufrufe. Ein produktiver Client braucht jedoch dieselben Grundlagen wie jeder andere Netzwerkdienst: getrennte Credentials, begrenzte Rechte, Zeitlimits, Statusprüfung und einen geschützten Transportweg.
