Okosotthon-automatizálás

A PrimeCal automatizálások két módon nyúlhatnak túl a naptáron, be az okosotthonába: egy eszköz REST API-jának közvetlen meghívásával, és egy rutinsablon igény szerinti példányosításával bármely triggerből. Mindkettő a meglévő automatizálási építőelemekre épül — nincs külön konfigurálandó „okosotthon" modul.

Egy okosotthon-eszköz REST API-jának meghívása

A Call Webhook (Webhook hívása) művelet HTTP-kérést küld a PrimeCal szervereiről. A célnak az internet felől, HTTPS-en keresztül elérhetőnek kell lennie. Az olyan rendszereket, amelyek csak az Ön otthoni hálózatán figyelnek, nem lehet közvetlenül meghívni. A művelet konfigurálható HTTP-metódust és elsőrangú hitelesítést is támogat, ami pontosan az, amit a legtöbb okosotthon-REST-API (Home Assistant, Shelly és hasonlók) elvár, amint ily módon elérhetővé tették.

A kérés konfigurálása

A műveletkészítőben a Call Webhook művelet a következőket teszi elérhetővé:

• Method (Módszer) — GET, POST, PUT, PATCH vagy DELETE (alapértelmezés szerint POST, ha nincs beállítva, kompatibilitás céljából az e mező bevezetése előtt mentett szabályokkal).
• Auth type (Hitelesítés típusa) — none, bearer, basic vagy header:
  • a bearer az Authorization: Bearer <token> fejlécet küldi.
  • a basic az Authorization: Basic <base64(user:pass)> fejlécet küldi — a tokent már user:pass formában kell megadni.
  • a header egy Ön által megadott egyéni fejlécnév alatt küldi el a tokent (hasznos olyan API-khoz, amelyek valami hasonlót várnak, mint az X-API-Key).
• Néhány gyakori előre beállított sablon (Home Assistant REST parancs, Shelly relé kapcsoló, általános Bearer-tokenes végpont) ésszerű alapértelmezett módszer- és hitelesítés-beállításokkal tölti ki előre magát, hogy ne kelljen ezekre emlékeznie.

Példa: mosógép bekapcsolása az ütemezett kezdési időpontjában

The Lates családnak van egy „Start laundry" (Mosás elindítása) feladata egy rutinsablonon belül. Amikor ez a feladat eléri az ütemezett kezdési időpontját, azt szeretnék, hogy a PrimeCal hívja meg a Home Assistant példányukat, és kapcsolja be a mosógép okos konnektorát.

Példa actionConfig a webhook művelethez:

{
  "url": "https://<your-instance>.ui.nabu.casa/api/webhook/<webhook-id>",
  "method": "POST",
  "authType": "bearer",
  "authToken": "YOUR_HOME_ASSISTANT_LONG_LIVED_TOKEN",
  "customPayload": { "entity_id": "switch.washing_machine" }
}

Ennek a szabálynak a triggere a task.scheduled_start — akkor sül el, amikor egy feladat (jelen esetben egy rutinelemből példányosított feladat) eléri az ütemezett kezdési időpontját. Ez a trigger még nincs benne a szabálykészítő trigger-választójában, ezért egy ilyen szabályt jelenleg közvetlenül az Automation API segítségével (vagy egy MCP-kapcsolt ügynökkel) hoznak létre, nem a felhasználói felület legördülő listájából.

A PrimeCal elutasítja azokat a kéréseket, amelyeket nem tud biztonságosan kézbesíteni

A Call Webhook kérés elutasításra kerül, mielőtt elküldenénk, ha:

• az URL nem HTTPS,
• a host localhost, .local-ra végződik, vagy privát/belső IP-címre oldódik fel,
• az URL felhasználónevet vagy jelszót tartalmaz, vagy
• a szerver átirányítással válaszol.

Egy csak a helyi hálózaton elérhető Home Assistant-példány (homeassistant.local, vagy bármely cím, amelyet csak az otthoni hálózata ér el) mindegyik feltételen elbukik. Tegye előbb elérhetővé — a Home Assistant Cloudon (Nabu Casa) keresztül, vagy saját, érvényes tanúsítvánnyal rendelkező reverse proxyval —, és helyette a /api/webhook/<id> útvonalát hívja.

Ne tartson tokeneket megosztott szabályokban

A hitelesítési tokenek a művelet konfigurációjának részeként tárolódnak. Egy klónozott vagy megosztott automatizálási szabályt ugyanúgy kezeljen, mint egy megosztott hitelesítő adatot — forgassa el a tokent, ha a szabályt valaha exportálják vagy olyan helyre másolják, ami felett nincs kontrollja.

Kész Home Assistant blueprint a másik irányhoz

A fenti példában a PrimeCal hívja meg a Home Assistantet. A fordított irányhoz — amikor a Home Assistant hívja meg a PrimeCal-t, vagy csak reagálni szeretne arra, amit a PrimeCal küld neki — töltse le a PrimeCal Webhook Action blueprintet, és importálja a Home Assistantbe (Settings → Automations & scenes → Blueprints → Import blueprint). Ez egy webhook-végpontot hoz létre a Home Assistant oldalán, és lehetővé teszi, hogy bármilyen műveletet kiválasszon, amely a PrimeCal hívásakor lefut, a PrimeCal által küldött adattal sablonváltozóként elérhetővé téve. Lásd az Automatizálási receptek oldalt a PrimeCal oldali megfelelő actionConfig-ért.

Rutin indítása bármely triggerből

Az instantiate_routine művelet lehetővé teszi, hogy bármely trigger — egy webhook, egy ütemezett időpont, egy létrehozott esemény, egy feladat állapotváltozása, vagy egy feladat ütemezett kezdési időpontjának elérése — azonnal elindítson egy rutinsablont, pontosan úgy, mintha a Start now gombra kattintott volna rajta. Lásd a Rutinok és sablonok oldalt arról, hogy mi az a rutinsablon, és milyen másik két módon indulhat el.

Példa: egy okos ébresztőóra elindítja a reggeli rutint

The Lates családnak van egy okos ébresztőórája, amely POST-kérést tud küldeni egy webhookra, amikor megszólal. Ahelyett, hogy minden reggel manuálisan megnyitnák a PrimeCalt, és a „Morning Routine" (Reggeli rutin) sablonon a Start now gombra kattintanának, összekötik az ébresztőórát egy olyan szabállyal, amely automatikusan példányosítja azt.

Példa actionConfig az instantiate_routine művelethez:

{
  "routineTemplateId": 42
}

A szabály felépítése:

1. Trigger: webhook.incoming — az okos ébresztőóra integrációja POST-kérést küld a szabály webhook URL-jére, amikor megszólal. Lásd a Webhookok oldalt arról, hogyan találja meg és hogyan küldjön erre az URL-re.
2. Action: instantiate_routine, a routineTemplateId beállítva The Lates családjának klónozott „Morning Routine" sablonjára.

A művelet ugyanazt a tulajdonjog-ellenőrzést használja újra, mint a manuális Start now gomb — egy szabály csak olyan rutinsablont példányosíthat, amelyet a tulajdonosa már amúgy is láthat (saját sablonjait, az emberek csoportján keresztül megosztott sablonokat, vagy aktív rendszersablonokat), soha egy másvalakihez tartozó, tetszőleges sablonazonosítót.

A task.scheduled_start triggerhez hasonlóan az instantiate_routine akciótípus még nincs benne a műveletválasztó legördülő listájában. Egy szabályt az Automation API segítségével hozzon létre vagy szerkesszen a használatához — például a PUT /api/automation/rules/:id végponttal, és egy actions tömbbel, amely a { "actionType": "instantiate_routine", "actionConfig": { "routineTemplateId": 42 } } elemet tartalmazza.

Lásd még

• Webhookok — egy szabály webhook URL-jének megkeresése és az arra való küldés
• A műveletek áttekintése — a műveletek típusainak teljes listája
• Rutinok és sablonok — mi az a rutinsablon, és hogyan működik a rotáció
• Automation API — szabályok létrehozása közvetlenül a task.scheduled_start, task.status_changed és instantiate_routine elemekkel