API Actors integráció

Módosítva ekkor Wed, Jan 7 ekkor: 5:05 DU

Az API Actors funkció lehetővé teszi, hogy a rendszer külső REST API-k felé HTTP kéréseket indítson különböző események hatására.
Ennek segítségével egyszerűen integrálhatók harmadik féltől származó rendszerek, backend szolgáltatások, automatizmusok vagy akár egyedi alkalmazások.

Az API Actor egy rugalmasan konfigurálható elem, amely meghatározott feltételek teljesülésekor (pl. állapotváltozás, esemény) HTTP hívást hajt végre.

API Actor létrehozása

Navigáljunk a Integrations → API Actors menüpontba.
Kattintsunk az + Add API Actor gombra.
Megjelenik az új API Actor konfigurációs felülete.

Az API Actor mentés után a bal oldali listában jelenik meg, ahol később bármikor szerkeszthető duplikálható vagy törölhető.

Konfigurálható mezők

Title - Az API Actor egyedi neve, amely segít azonosítani az integráció célját.

Activation Type - Meghatározza, hogy mikor történjen meg a HTTP kérés elküldése.

OnEvent
A kérés minden alkalommal elküldésre kerül, amikor a trigger esemény lefut – akkor is, ha az érték nem változott.
OnChange
A kérés csak akkor kerül elküldésre, ha a trigger értéke megváltozott.
Periodic
A kérés meghatározott időközönként kerül elküldésre, az „Activation Period” beállítás szerint.

Activation Source - Megadja, hogy mely rendszerkomponens generálja az eseményt.

StateRegister
ZoneTargetTemperature
ZoneCurrentTemperature
ZoneHumidity
ZoneTargetState
ZoneState
ZoneFanSpeed
ZoneEcoMode

Trigger - Az a konkrét azonosító, amelyhez az aktiválás kötődik (egy State register ID, vagy a zóna neve).

HTTP Method - A küldendő HTTP kérés típusa:

GET
POST
PUT
DELETE
PATCH

Body Type - A kérés törzsének típusa

Raw – szabadon megadható tartalom
JSON - strukturált JSON formátum

Body - A HTTP kérés törzse.
Lehetőség van a trigger aktuális értékének beillesztésére a `{value}` jelöléssel.

HTTP Url - A cél API végpont teljes URL-je.

Példa (ha a 10-es stateregister id eszközre szeretnénk küldeni):

http://<IP cím>:9000/v1/states/10

Authorization Type - Az API Actor többféle hitelesítési módot támogat.

BearerToken
A megadott token automatikusan Authorization: Bearer <token> formában kerül elküldésre.
BasicAuth
A mező formátuma:
```
username:password
```
UrlParameter
A token URL paraméterként kerül hozzáadásra (a ? karakter automatikusan hozzá van adva).
None
Nincs hitelesítés.

Authorization Body - A kiválasztott hitelesítési módhoz tartozó érték (token, felhasználónév/jelszó stb.).

Mentés és kezelés

Save – API Actor mentése
Duplicate API Actor – meglévő konfiguráció klónozása
Delete API Actor – API Actor törlése

A képen a 12-es state register id állapotát küldjük el a 10-es register id-nak 60 másodpercenként. Így a két eszköz 60 másodpercenként "szinkronizálódik" a 12-es register szerint. A HTTP Url "localhost" része a saját Controllerünkre utal, így ha egyazon Controller a küldő és fogadó szerepet is betölti, nem kell lefixálnunk az Ip címet feltétlenül, mert a localhost tudni fogja. Hitelesítésnek a BearerToken-t választottuk, ahol az Authorization Body a fogadó Controller API Key-e.

Fontos figyelembe venni, hogy ez az integráció csak akkor működik helyesen, ha a REST API engedélyezve van mind a küldő, mind pedig a fogadó Controlleren!