HTTP
In Macro Deck enthaltenSende HTTP-Anfragen per Taste und speichere Werte aus der Antwort in Variablen.
Die Seite der Integration HTTP mit eingeschaltetem Schalter und ohne Konfigurationsoptionen
- GET, POST, PUT, PATCH, DELETE und mehr, mit Query und Headern
- Authentifizierung per Basic, Bearer-Token oder API-Schlüssel im Header
- Bodys als JSON, Formular, Text oder Datei-Upload
- Status, Header oder JSON-Werte in Variablen speichern
- Variablen in den Werten von Query-Parametern und Headern
Die HTTP-Integration sendet Web-Anfragen aus Macro Deck. Nutze sie, um einen Webhook aufzurufen, ein Gerät mit Web-API in deinem Netzwerk zu steuern oder einen Wert von einem Online-Dienst zu lesen und auf einer Taste anzuzeigen. Sie ist in Macro Deck enthalten und von Anfang an aktiv, du musst also nichts verbinden und dich nirgends anmelden.
Zwei Aktionen
HTTP-Anfrage senden baut eine vollständige Anfrage. Du wählst die Methode, gibst die URL ein und fügst Query-Parameter und Header als Name-Wert-Paare hinzu. Unter Body-Typ wählst du none, json, form, text oder multipart (ein Datei-Upload mit zusätzlichen Formularfeldern). Authentifizierung bietet basic (Benutzername und Passwort), bearer (ein Token) und header (ein Token in einem Header, den du benennst, zum Beispiel X-Api-Key). Erwarteter Status legt fest, welche Antworten als Erfolg gelten, standardmäßig 2xx. Außerdem kannst du das Timeout festlegen, Weiterleitungen folgen abschalten und die Maximale Antwortgröße (Bytes) begrenzen.
Erfassungen speichern Teile der Antwort in Variablen. Jede Zeile ordnet einem Variablennamen einen Selektor zu: $status, $ok, $duration, $body, $truncated, $headers, $header:<name> oder einen JSON-Pfad wie data.items[0].name. Eine Variable, die es noch nicht gibt, wird angelegt.
JSON-Wert abrufen ist die Kurzform, um einen einzelnen Wert zu lesen: Gib die URL, einen JSON-Pfad und unter In Variable speichern die Variable an.
Beispiele
- Eine Taste, die mit HTTP-Anfrage senden und dem Body-Typ
json{"text": "Stream is live"}an einen Chat-Webhook sendet. - Eine Taste, die eine smarte Steckdose in deinem Netzwerk über ihre lokale Web-API einschaltet.
- Eine Taste, die mit JSON-Wert abrufen den aktuellen Preis aus einer öffentlichen API liest und ihn mit
{{ vars.price }}in ihrer Beschriftung zeigt. - Ein Ablauf, der eine Anfrage sendet,
$statuserfasst und mit Wenn / Sonst die Taste rot färbt, wenn der Server nicht mit200geantwortet hat.
Die Werte von Query-Parametern und Headern können Variablen enthalten, zum Beispiel {{ vars.channel }}. Die Anfrage läuft auf dem Computer, auf dem Macro Deck läuft, daher erreichen Adressen wie http://192.168.1.20 Geräte im Netzwerk dieses Computers. Eine Aktion schlägt mit einer klaren Meldung fehl, wenn der Server nicht erreichbar ist, die Anfrage in ein Timeout läuft, das TLS-Zertifikat abgelehnt wird oder der Status nicht der erwartete ist.
Das brauchst du
- Macro Deck 3 unter Windows, macOS oder Linux
- Die Adresse der Web-API oder des Webhooks, den du aufrufen willst
- Einen API-Schlüssel, ein Token oder ein Passwort, falls der Dienst eines braucht
So richtest du sie ein
Schritt 1: Prüfen, ob die Integration aktiv ist
Klicke in Macro Deck in der Seitenleiste auf Integrationen und dann auf HTTP. Der Schalter oben rechts ist standardmäßig eingeschaltet; schalte ihn ein, falls er aus ist. Es gibt nichts einzurichten: Der Tab Übersicht zeigt Für diese Integration sind keine Konfigurationsoptionen verfügbar.
Schritt 2: HTTP-Aktion zu einer Taste hinzufügen
Klicke auf der Seite Deck auf eine Taste. Das Deck muss entsperrt sein: Das ist es, wenn oben rechts die Schaltfläche Sperren zu sehen ist. Der Editor öffnet sich mit ausgewähltem Kurzer Druck. Klicke auf + Aktion hinzufügen, wähle links im Dialog Aktion hinzufügen HTTP und nimm HTTP-Anfrage senden oder JSON-Wert abrufen, wenn du nur einen Wert lesen willst. Du kannst den Namen auch in Aktionen durchsuchen… eintippen.
Schritt 3: Anfrage eingeben
Wähle die Methode und gib die URL ein. Füge Query-Parameter und Header hinzu, wenn die API sie braucht. Für eine Anfrage mit Daten wählst du den Body-Typ und füllst JSON-Body, Formularfelder oder Text-Body aus.
Schritt 4: Authentifizierung hinzufügen
Braucht der Dienst eine Anmeldung oder einen Schlüssel, wähle sie unter Authentifizierung:
basicmit Benutzername und Passwort / Token,bearermit dem Token in Passwort / Token oderheadermit dem Feld Header-Name und dem Schlüssel in Passwort / Token. Die meisten Dienste zeigen ihre API-Schlüssel oder Tokens in den Konto- oder Entwicklereinstellungen.Schritt 5: Werte aus der Antwort speichern
Um die Antwort zu nutzen, füge unter Erfassungen Zeilen hinzu: einen Variablennamen und einen Selektor wie
$statusoder einen JSON-Pfad wiedata.temperature. Bei JSON-Wert abrufen gibst du den JSON-Pfad ein und wählst die Variable unter In Variable speichern.Schritt 6: Taste ausprobieren
Klicke im Editor auf Ausführen, um die Anfrage sofort zu senden, oder speichere und drücke die Taste. Schlägt die Aktion fehl, sagt ihre Meldung dir, warum, zum Beispiel dass der Server nicht erreichbar war oder der Status nicht zu Erwarteter Status passte.
Aktionen2
Lege sie auf eine Taste oder führe sie in einem Ablauf aus.
- HTTP-Anfrage senden
- Sendet eine konfigurierbare HTTP-Anfrage und kann die Antwort in Variablen erfassen.
- JSON-Wert abrufen
- Ruft eine URL ab und schreibt einen Wert aus der JSON-Antwort in eine Variable.
Häufige Fragen
Wo werden meine API-Schlüssel und Passwörter gespeichert?
Was du in Passwort / Token eingibst, wird verschlüsselt gespeichert und erst beim Senden der Anfrage in Klartext umgewandelt. Werte, die du in Header eintippst, werden unverschlüsselt gespeichert und stecken in exportierten Profilen, also gehören Schlüssel und Tokens besser in die Authentifizierungsfelder.
Kann ich ein Gerät in meinem lokalen Netzwerk aufrufen?
Ja. Die Anfrage wird von dem Computer gesendet, auf dem Macro Deck läuft, daher funktioniert jede Adresse, die dieser Computer erreicht. Für ein Gerät mit selbstsigniertem Zertifikat kannst du TLS-Zertifikat prüfen abschalten, aber tu das nur für Geräte in deinem eigenen Netzwerk.
Warum schlägt die Aktion fehl, obwohl der Server geantwortet hat?
Die Antwort passte nicht zu Erwarteter Status, standardmäßig 2xx. Gib den Statuscode ein, den die API tatsächlich zurückgibt, einen Bereich wie 200-204, eine Liste oder any, um jeden Status zu akzeptieren. JSON-Wert abrufen erwartet immer eine 2xx-Antwort.
Welche JSON-Pfade kann ich verwenden?
Verwende Punkte und Indizes, zum Beispiel data.items[0].name oder [0].id, oder $ für das ganze Dokument. In Erfassungen haben die reservierten Selektoren wie $status Vorrang, ein Feld, das wirklich status heißt, liest du also mit $.status.
Muss ich die Variablen vorher anlegen?
Nein. Nennt eine Erfassung oder In Variable speichern eine Variable, die es nicht gibt, legt Macro Deck sie an. Gibt es bereits eine Variable mit diesem Namen, aber einem anderen Typ, schlägt das Speichern mit einer Meldung fehl.
Mehr in „Smart Home und Web“
Home Assistant
In Macro Deck enthaltenSchalte Lichter, starte Szenen und Skripte und zeige Live-Zustände aus deinem Home Assistant auf deinem Deck.
AdGuard Home
In Macro Deck enthaltenSchalte den Schutz von AdGuard Home ein, aus oder pausiere ihn und zeige seine Statistiken auf deinem Deck.
RSS-Feeds
In Macro Deck enthaltenFolge RSS- und Atom-Feeds, zeige ihre neuesten Artikel in Widgets und reagiere, wenn neue Artikel erscheinen.
Wetter
In Macro Deck enthaltenZeige das aktuelle Wetter und die Vorhersage für deine Orte auf deinem Deck, ohne API-Schlüssel.