Web Request in der Gira X1 Logik-Ansicht
Was ist der Web Request-Baustein?
Der Web Request-Baustein ermöglicht das Senden beliebiger HTTP-Anfragen direkt aus dem Gira X1 oder L1 System. Damit lassen sich REST-APIs ansprechen, Webhooks auslösen, Smart-Home-Geräte steuern und Daten von externen Diensten abrufen.
Der Baustein unterstützt alle gängigen HTTP-Methoden, Authentifizierung per Basic Auth oder Bearer Token, bis zu 10 eigene Header, dynamische Variablen-Platzhalter in URL und Body sowie einen konfigurierbaren Timeout und SSL-Zertifikat-Bypass für lokale Geräte.
Hauptfunktionen
Alle HTTP-Methoden
GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS und CONNECT werden unterstützt. Der Content-Type und Body werden bei POST/PUT automatisch eingeblendet.
Authentifizierung
Basic Auth (Benutzername/Passwort) und Bearer Token werden unterstützt. Die Felder werden je nach Auswahl dynamisch ein- und ausgeblendet.
Variablen-Platzhalter
In URL und Body können Platzhalter wie {temperatur} verwendet werden. Der Baustein erkennt diese automatisch und erstellt für jeden Platzhalter einen eigenen Eingang.
HTTPS & SSL-Bypass
HTTPS wird vollständig unterstützt – auch zu Cloud-APIs wie OpenWeatherMap oder Pushover. Für lokale Geräte mit selbstsignierten Zertifikaten kann die SSL-Prüfung deaktiviert werden.
Hinweis: Netzwerkverbindung erforderlich
Der Gira X1 / L1 muss eine Netzwerkverbindung zum Zielserver haben. Bei Cloud-APIs muss der X1 Internetzugang besitzen.
Eingänge und Parameter
Eingänge
| Eingang | Beschreibung |
|---|---|
| Trigger | Eine steigende Flanke (true) löst den Web Request aus |
Parameter
| Parameter | Beschreibung |
|---|---|
| URL | Ziel-URL, unterstützt {Variablen}-Platzhalter, z.B. http://192.168.1.100/api/{endpoint} |
| Methode | HTTP-Methode: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT |
| Authentifizierung | (keine), Basic Auth oder Bearer Token |
| Benutzername | Nur bei Basic Auth sichtbar |
| Passwort | Nur bei Basic Auth sichtbar |
| Token | Nur bei Bearer Token sichtbar |
| Content-Type | Nur bei POST/PUT/etc. sichtbar: text/plain, application/json, application/xml, x-www-form-urlencoded |
| Body | Nur bei POST/PUT/etc. sichtbar, unterstützt {Variablen}-Platzhalter |
| Timeout (Sekunden) | Maximale Wartezeit in Sekunden (Standard: 10) |
| SSL-Zertifikat ignorieren | Deaktiviert die Zertifikatprüfung für HTTPS-Verbindungen mit selbstsignierten Zertifikaten |
| Eigene Header setzen | Anzahl eigener HTTP-Header (0 bis 10) |
| Header #1 bis #10 | Eigene HTTP-Header im Format Name: Wert |
| {Variablen} | Dynamisch erkannte Platzhalter aus URL und Body (werden automatisch als Eingänge angelegt) |
Ausgänge
| Ausgang | Beschreibung |
|---|---|
| Antwort | Response-Body bei erfolgreichem Request (maximal 64 KB) |
| Erfolg | Gibt Wahr aus, wenn der letzte Request erfolgreich war |
| Beschäftigt | Gibt Wahr aus, solange ein Request läuft |
| Fehlercode (HTTP Status) | HTTP-Statuscode bei Fehler oder interner Fehlercode (siehe Fehlerbehebung) |
| Fehlermeldung | Detaillierte Fehlerbeschreibung im Fehlerfall |
Anwendungsbeispiele
Fronius Wechselrichter abfragen (GET)
Ausgangssituation:
Die aktuelle PV-Leistung soll vom Fronius Wechselrichter per Solar-API abgerufen werden.
Konfiguration:
URL: http://192.168.1.50/solar_api/v1/GetInverterRealtimeData.cgi?Scope=Device&DeviceId=1&DataCollection=CommonInverterData
Methode: GET, Timeout: 5, Authentifizierung: (keine)
Pushover Benachrichtigung senden (POST)
Anwendungsfall: Push-Nachricht bei Alarm aufs Handy senden.
Konfiguration:
URL: https://api.pushover.net/1/messages.json
Methode: POST, Content-Type: application/x-www-form-urlencoded
Body: token={appToken}&user={userKey}&message={nachricht}
Ergebnis:
Die Variablen {appToken}, {userKey} und {nachricht} werden automatisch als Eingänge angelegt. Bei jedem Trigger wird die Push-Nachricht versendet.
Shelly Relais schalten (GET)
Anwendungsfall: Shelly-Relais per HTTP ein- oder ausschalten.
Konfiguration:
URL: http://192.168.1.80/relay/0?turn={zustand}
Methode: GET, Timeout: 5
Ergebnis:
Die Variable {zustand} wird als Eingang angelegt und kann mit on oder off belegt werden.
Home Assistant API mit Bearer Token
Anwendungsfall: Zustand einer Entität über die Home Assistant REST-API abfragen.
Konfiguration:
URL: http://192.168.1.10:8123/api/states/{entity}
Methode: GET, Authentifizierung: Bearer Token
Token: Ihr Long-Lived Access Token
IP-Kamera mit Basic Auth und SSL-Bypass
Anwendungsfall: Snapshot einer lokalen IP-Kamera mit selbstsigniertem Zertifikat abrufen.
Konfiguration:
URL: https://192.168.1.90/snap.cgi
Methode: GET, Authentifizierung: Basic Auth
SSL-Zertifikat ignorieren: Wahr, Timeout: 10
Fehlerbehebung
| Fehlercode | Bedeutung | Lösung |
|---|---|---|
| 401 | Unauthorized | Zugangsdaten oder Token prüfen, richtigen Authentifizierungstyp auswählen |
| 403 | Forbidden | Rechte des Tokens prüfen, ggf. neuen Token generieren |
| 404 | Not Found | URL und Endpunkt prüfen, Gross-/Kleinschreibung beachten |
| 500 | Internal Server Error | Fehler auf dem Zielserver, Body und Parameter prüfen |
| 995 | Timeout | Server antwortet nicht rechtzeitig. Timeout-Wert erhöhen oder Netzwerk prüfen |
| 996 | Request läuft bereits | Vorheriger Request noch nicht abgeschlossen. Trigger-Frequenz reduzieren |
| 998 | Verbindungsfehler | DNS-Auflösung fehlgeschlagen, Verbindung verweigert oder SSL-Fehler. IP, Port, Hostname und Netzwerk prüfen. Bei SSL-Fehlern „SSL-Zertifikat ignorieren" aktivieren |
| 999 | Allgemeiner Fehler | Unerwarteter Fehler. Die Fehlermeldung enthält weitere Details |
Wichtig: SSL-Bypass nur für lokale Geräte
Deaktivieren Sie die SSL-Zertifikatprüfung ausschließlich für Geräte im eigenen Netzwerk mit selbstsignierten Zertifikaten (Wechselrichter, IP-Kameras, NAS). Aktivieren Sie diese Option niemals für Cloud-Dienste oder Internet-APIs.
Wichtig: Zugangsdaten
Passwörter und Tokens werden im Klartext in der GPA-Konfiguration gespeichert. Schützen Sie den Zugang zum Gira GPA entsprechend.
Tipp: Timeout anpassen
Für lokale Geräte (Shelly, Wechselrichter) genügen 3 bis 5 Sekunden. Für Cloud-APIs (Pushover, Telegram) empfehlen sich 10 bis 15 Sekunden. Für langsame Endpunkte wie Kamera-Snapshots können 15 bis 30 Sekunden sinnvoll sein.
Changelog
Erstveröffentlichung.