Použitím TapHome API je možné integrovať zariadenia TapHome do akejkoľvek aplikácie tretej strany. Napríklad hlasové ovládanie Apple Siri.
TapHome API definuje sadu funkcií, na ktoré môžu vývojári vykonávať požiadavky a prijímať odpovede. Interakcia sa vykonáva prostredníctvom protokolu HTTP. Výhodou takéhoto prístupu je široké využitie HTTP. Preto je TapHome API možné použiť prakticky pre akýkoľvek programovací jazyk.
Prehľad TapHome API:
TapHome API funguje aj prostredníctvom lokálnej siete. Prístup k jadru lokálne znižuje latenciu komunikácie a robí systém nezávislým od internetového pripojenia. Špecifikácia (autentifikácia, požiadavky, odpovede) je identická s cloudovou verziou. TapHome API cez lokálnu sieť podporuje iba HTTP protokol a neobsahuje používateľské rozhranie Swagger.
Kedykoľvek je to možné, použite lokálne TapHome API. Časy odozvy sú kratšie a pravdepodobnosť zlyhania požiadavky je výrazne nižšia v porovnaní s cloudom, kde dáta cestujú z vášho domova do cloudu a späť cez internet. Pri použití lokálneho TapHome API musí mať jednotka Core nastavenú pevnú IP adresu alebo používať mDNS.
TapHome TapHome API používa vlastnú HTTP schému založenú na Basic access authentication. Nevyžaduje cookies, identifikátor relácie ani prihlasovacie stránky. TapHome TapHome API však nepoužíva kombináciu prihlasovacieho mena a hesla, ale zdieľané tajomstvo nazývané token.
Vlastná hlavička HTTP pre autentifikáciu je vytvorená nasledovne:
Authorization: TapHome {token}
Príklad autentifikačnej HTTP požiadavky:
GET /api/TapHomeApi/v1/location HTTP/1.1
Host: api.taphome.com
Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32
Príklad použitia curl:
curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://api.taphome.com/api/TapHomeApi/v1/location"
Keď systém prijme autentifikovanú požiadavku, načíta token, ktorý si nárokujete, a použije ho na identifikáciu umiestnenia riadiacej jednotky TapHome. Ak sa token nezhoduje so záznamami TapHome, požiadavka je zamietnutá a systém odpovie chybovou správou (typicky HTTP 401).
Alternatívne je tiež možné vložiť token do parametrov dotazu (iba pre volania HTTP GET). Dôrazne odporúčame neposkytovať takéto URL tretím stranám, pretože token môže byť použitý na prístup a ovládanie akéhokoľvek zariadenia vystaveného riadiacou jednotkou.
V aplikácii TapHome prejdite na Nastavenia → Sprístupniť zariadenia → TapHome API. V kontextovom menu (tri bodky vpravo hore) použite funkciu Vytvoriť nový prístupový token. Pozor – vždy, keď vygenerujete nový token, pôvodné príkazy URL prestanú fungovať. Kliknite na šípku vedľa tokenu a sprievodca ho skopíruje do schránky.
V prípade, že bol token kompromitovaný a je potrebné ho zrušiť, je možné vygenerovať nový token pomocou TapHome. Aktívny je vždy iba jeden token.
Získa informácie o polohe riadiacej jednotky. Použite toto volanie na kontrolu, či je poloha online.
Variant 1
GET /api/TapHomeApi/v1/location
Parametre: žiadne
Variant 2
POST /api/TapHomeApi/v1/location
Parametre: žiadne
Príklad odpovede:
{
"locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b",
"locationName": "Test Location",
"timestamp": 855000000000
}
Možné chyby stavu HTTP:
Získa zariadenia sprístupnené riadiacou jednotkou. Pre každé zariadenie je poskytnutý zoznam typov hodnôt (obsahujúci ID typu hodnoty a názov typu hodnoty). Niektoré z hodnôt môžu byť len na čítanie (napr. Stav zariadenia).
Na nastavenie hodnôt zariadenia musíte poskytnúť valueTypeId na identifikáciu vlastnosti zariadenia, ktorá sa nastaví.
Variant 1
GET /api/TapHomeApi/v1/discovery
Parametre: žiadne
Variant 2
POST /api/TapHomeApi/v1/discovery
Parametre: žiadne
Príklad odpovede:
{
"devices": [
{
"deviceId": 1,
"type": "VirtualAnalogOutput",
"name": "My AO",
"description": "My AO Description",
"supportedValues": [
{
"valueTypeId": 7,
"valueTypeName": "DeviceStatus"
},
{
"valueTypeId": 42,
"valueTypeName": "AnalogOutputValue"
},
{
"valueTypeId": 48,
"valueTypeName": "SwitchState"
},
{
"valueTypeId": 67,
"valueTypeName": "AnalogOutputDesiredValue"
}
]
},
{
"deviceId": 2,
"type": "VirtualBlindGroup",
"name": "My Blind Group",
"description": "My Blind Group Description",
"supportedValues": [
{
"valueTypeId": 7,
"valueTypeName": "DeviceStatus"
},
{
"valueTypeId": 10,
"valueTypeName": "BlindsSlope"
},
{
"valueTypeId": 46,
"valueTypeName": "BlindsLevel"
}
]
}
],
"timestamp": 855000000000
}
Možné chyby stavu HTTP:
Získa všetky aktuálne hodnoty pre dané zariadenie a ich typy. Prvky hodnoty sa skladajú z ID typu hodnoty, názvu typu hodnoty a aktuálnej hodnoty. Niektoré z hodnôt môžu byť iba na čítanie (napr. Stav zariadenia).
Na nastavenie hodnôt zariadenia musíte poskytnúť valueTypeId na identifikáciu vlastnosti zariadenia, ktorá sa nastaví. Typ hodnoty je vždy číslo (double).
Príliš časté vyžiadanie rovnakej hodnoty (menej ako 500 ms medzi požiadavkami) môže vrátiť hodnotu z cache namiesto každého načítania aktuálnej hodnoty z riadiacej jednotky. Odpovede s rovnakými časovými značkami sa vzťahujú na rovnakú hodnotu. Nepredpokladajte, že hodnota časovej značky vždy rastie, mala by sa porovnávať iba pre rovnosť.
Variant 1
GET /api/CloudApi/v1/getDeviceValue/{deviceId}
Parametre: ID zariadenia v ceste URL (napr. „1“)
Variant 2
POST /api/CloudApi/v1/getDeviceValue
Parametre:
{
"deviceId": 1
}
Príklad odpovede:
{
"deviceId": 1,
"values": [
{
"valueTypeId": 7,
"valueTypeName": "DeviceStatus",
"value": 0
},
{
"valueTypeId": 22,
"valueTypeName": "OperationMode",
"value": 0
},
{
"valueTypeId": 23,
"valueTypeName": "ManualTimeout",
"value": 0
},
{
"valueTypeId": 42,
"valueTypeName": "AnalogOutputValue",
"value": 1
},
{
"valueTypeId": 48,
"valueTypeName": "SwitchState",
"value": 1
},
{
"valueTypeId": 67,
"valueTypeName": "AnalogOutputDesiredValue",
"value": 1
}
],
"timestamp": 855000000000
}
Možné chyby stavu HTTP:
Získa všetky aktuálne hodnoty pre dané zariadenia a ich typy. Prvky hodnoty odpovede sa skladajú z ID typu hodnoty, názvu typu hodnoty a skutočnej hodnoty. Niektoré hodnoty môžu byť len na čítanie (napr. Stav zariadenia). ID typu hodnoty je voliteľné. Táto funkcia vyžaduje verziu Core 2021.3 alebo novšiu.
Zvážte získanie viacerých hodnôt naraz s jedným API volaním, aby ste ušetrili šírku pásma a poslali primeraný počet požiadaviek na server TapHome API.
POST /api/CloudApi/v1/getMultipleDevicesValues
Parametre:
{
"devices": [
{
"deviceId": 1,
"valueTypeId": 7
},
{
"deviceId": 2
}
],
"timestamp": 855000000000
}
Príklad odpovede:
{
"devices": [
{
"deviceId": 1,
"values": [
{
"valueTypeId": 7,
"valueTypeName": "DeviceStatus",
"value": 0
}
]
},
{
"deviceId": 2,
"values": [
{
"valueTypeId": 7,
"valueTypeName": "DeviceStatus",
"value": 0
},
{
"valueTypeId": 10,
"valueTypeName": "BlindsSlope",
"value": 1.0
},
{
"valueTypeId": 46,
"valueTypeName": "BlindsLevel",
"value": 0.0
}
]
}
],
"timestamp": 855000000000
}
Možné chyby stavu HTTP:
Získa všetky aktuálne hodnoty všetkých zariadení naraz. Prvky hodnoty odpovede sa skladajú z ID typu hodnoty, názvu typu hodnoty a aktuálnej hodnoty. Niektoré hodnoty môžu byť len na čítanie (napr. Stav zariadenia). Táto funkcia vyžaduje verziu Core 2021.3 alebo novšiu.
Zvážte získanie viacerých hodnôt naraz s jedným API volaním, aby ste ušetrili šírku pásma a poslali primeraný počet požiadaviek na server TapHome API.
Variant 1
GET /api/CloudApi/v1/getAllDevicesValues
Variant 2
POST /api/CloudApi/v1/getAllDevicesValues
Príklad odpovede:
{
"devices": [
{
"deviceId": 1,
"values": [
{
"valueTypeId": 7,
"valueTypeName": "DeviceStatus",
"value": 0
},
{
"valueTypeId": 42,
"valueTypeName": "AnalogOutputValue",
"value": 1
},
{
"valueTypeId": 48,
"valueTypeName": "SwitchState",
"value": 1
},
{
"valueTypeId": 67,
"valueTypeName": "AnalogOutputDesiredValue",
"value": 1
}
]
},
{
"deviceId": 2,
"values": [
{
"valueTypeId": 7,
"valueTypeName": "DeviceStatus",
"value": 0
},
{
"valueTypeId": 10,
"valueTypeName": "BlindsSlope",
"value": 1.0
},
{
"valueTypeId": 46,
"valueTypeName": "BlindsLevel",
"value": 0.0
}
]
}
],
"timestamp": 855000000000
}
Možné chyby stavu HTTP:
Získa jednu aktuálnu hodnotu pre dané zariadenie a ID typu hodnoty ako text – nevyžaduje žiadne spracovanie JSON. Táto funkcia je ideálna pre jednoduché integrácie. Typicky by ste zahrnuli token aj do reťazca dotazu, takže všetky potrebné parametre sú poskytnuté v URL a nastavenie HTTP hlavičiek nie je potrebné.
Odpoveď je vždy číslo (double), formátované na reťazec s použitím desatinnej čiarky a nepoužíva žiadne oddeľovače tisícov ani vedeckú notáciu. Ak je hodnota neznáma, odpoveďou je NaN.
Príliš časté vyžiadanie rovnakej hodnoty (menej ako 500 ms medzi požiadavkami) môže vrátiť hodnotu z cache namiesto každého načítania aktuálnej hodnoty z riadiacej jednotky.
GET /api/CloudApi/v1/getOneDeviceValue/{deviceId}?valueTypeId={valueTypeId}&token={theToken}
Parametre: ID zariadenia v ceste URL (napr. „1“) parametre dotazu – ID typu hodnoty (napr. „42“)
Príklad odpovede:
1.27
Možné chyby stavu HTTP:
Nastaví jednu alebo viacero hodnôt zariadenia s danými typmi. Ostatné hodnoty zariadenia zostávajú nezmenené.
Typ hodnoty je vždy číslo (double).
Nastavenie rovnakej hodnoty príliš často (menej ako 500 ms medzi požiadavkami) vedie k chybe HTTP 503.
Variant 1
GET /api/TapHomeApi/v1/setDeviceValue/{deviceId}?valueTypeId={valueTypeId1}&value={value1}&valueTypeId2={valueTypeId2}&value2={value2}&valueTypeId3={valueTypeId3}&value3={value3}&token={theToken}
Parametre: ID zariadenia v ceste URL (napr. „2“) parametre dotazu – až tri hodnoty a ich typy (napr. valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)
Tento variant funkcie je ideálny pre jednoduché integrácie, nevyžaduje žiadne spracovanie JSON. Typicky by ste token zahrnuli aj do reťazca dotazu, takže všetky potrebné parametre sú poskytnuté v URL a nastavenie HTTP hlavičiek nie je potrebné.
Variant 2
POST /api/TapHomeApi/v1/setDeviceValue
Parametre:
{
"deviceId": 2,
"values": [
{
"valueTypeId": 46,
"value": 0.1
},
{
"valueTypeId": 10,
"value": 0.2
}
]
}
Príklad odpovede:
{
"deviceId": 2,
"valuesChanged": [
{
"typeId": 46,
"result": "changed"
},
{
"typeId": 10,
"result": "notchanged"
},
{
"typeId": 7,
"result": "failed"
}
],
"timestamp": 855000000000
}
Možné chyby stavu HTTP:
Funkcia webhook sa používa na odosielanie zmien hodnôt sprístupnených zariadení prostredníctvom protokolu HTTP. Volá nakonfigurovanú URL a odosiela nový stav zariadenia, či už v rámci LAN alebo cez internet. Použitie webhooku umožňuje efektívnejšiu synchronizáciu stavov zariadení riadiacej jednotky Core s externým prostredím v porovnaní s periodickým dotazovaním (polling). Kedykoľvek je to možné, použite webhook v kombinácii s periodickým dotazovaním v dlhších intervaloch (minúty alebo desiatky minút, v prípade zlyhania webhooku). Je k dispozícii iba jeden webhook, bez ohľadu na to, či sa používa lokálne alebo cloudové API.
Keďže sa niektoré hodnoty zariadení môžu meniť veľmi často, spustenie webhooku by mohlo preťažiť prijímajúcu stranu alebo porušiť zásady spravodlivého používania; preto sa webhook aktivuje maximálne každých 300 ms. To znamená, že zmeny sa doručujú s maximálnym oneskorením 300 ms, pričom sa odosiela iba najnovšia hodnota sprístupneného zariadenia. Ak sa hodnota zariadenia zmení do 300 ms z 1 na 2, 3, … 100, webhook odošle iba hodnotu 100. Ak odoslanie zlyhá, neopakuje sa.
Webhook vždy používa metódu HTTP POST. Aplikácia umožňuje konfigurovať tri vlastné hlavičky HTTP požiadaviek vo formáte „kľúč: hodnota“.
Odoslané dáta – štruktúra dát je identická s volaním „getMultipleDevicesValues“.