TapHome API

Pomocou TapHome API je možné integrovať zariadenia TapHome do akejkoľvek aplikácie tretej strany. Napríklad hlasové ovládanie Apple Siri.

Pokiaľ máte záujem o priamu komunikáciu s Riadiacou jednotkou v rámci LAN alebo VPN, zvážte použiť

Integration Protocol (AMX, Lutron, Crestron, Control4, Clipsal)

Prehľad

TapHome API definuje množinu 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é použitie protokolu HTTP. Preto je možné TapHome API použiť prakticky pre akýkoľvek programovací jazyk.

TapHome TapHome API prehľad:

K prostriedku pristupujete odoslaním žiadosti HTTP na server TapHome TapHome API. Server odpovie odpoveďou, ktorá obsahuje údaje, ktoré ste požadovali
Všetky zdroje sa nachádzajú na https://api.taphome.com/api/TapHomeApi/v1/
Všetky zdroje môžu vracať rôzne stavové kódy HTTP (napr. Stavový kód HTTP 200 pre úspešnú odpoveď alebo stavový kód HTTP 400 pre zlú požiadavku)
Požadujete konkrétny zdroj tak, že na základnú adresu URL, ktorá špecifikuje zdroj, pridáte konkrétnu cestu
Je poskytnutá štandardná dokumentácia o napodobňovaní spolu s testovacím prostredím
Všetky odpovede sú vo formáte Json a používajú kódovanie znakov UTF-8

TapHome Core verzia 2021.3 prináša novú funkciu: TapHome API prostredníctvom lokálnej siete. Prístup k Core lokálne znižuje latenciu komunikácie a robí systém nezávislým na internetovom pripojení. Špecifikácia (autentifikácia, požiadavky, odpovede) je identická s cloudovou verziou. TapHome API v miestnej sieti podporuje iba protokol HTTP a neobsahuje používateľské rozhranie Swagger.

Autentifikácia TapHome API požiadaviek

TapHome TapHome API používa vlastnú schému HTTP založenú na základnom overení prístupu. Nevyžaduje súbory cookie, identifikátor relácie ani prihlasovacie stránky. TapHome TapHome API však nepoužíva pár login: heslo, ale zdieľané tajomstvo zvané token.

Hlavička HTTP vlastnej autentifikácie má tento tvar:

Authorization: TapHome {token}

Príklad požiadavky HTTP na overenie totožnosti:

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ú žiadosť, načíta token, ktorý údajne máte, a použije ho na identifikáciu umiestnenia jednotky TapHome Control. Ak sa token nezhoduje so záznamami TapHome, požiadavka sa zruší a systém odpovie chybovou správou (zvyčajne HTTP 401).

Alternatívne je tiež možné vložiť token do parametrov dotazu (iba pre hovory HTTP GET). Dôrazne odporúčame, aby ste také adresy URL neposkytovali tretím stranám, pretože token sa môže použiť na prístup a kontrolu nad akýmkoľvek zariadením vystaveným riadiacou jednotkou.

Ako získať token

V aplikácii TapHome prejdite do Nastavenia → Vystaviť 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é URL príkazy prestávajú fungujať. Kliknutím na šípku vedľa tokenu Sprievodca ho skopíruje do schránky.

V prípade, že bol token napadnutý a je potrebné ho odvolať, je možné pomocou aplikácie TapHome vygenerovať nový token. Aktívny je vždy iba jeden token.

TapHome API Referencia

Získajte informácie o polohe

Získa informácie o umiestnení riadiacej jednotky. Pomocou tejto výzvy skontrolujte, či je miesto 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:

401 Neoprávnené
404 Nenašiel sa - umiestnenie nie je pripojené k cloudu
405 Metóda nie je povolená - dopyt alebo parametre sú neplatné
500 Interná chyba servera

Vyhľadajte zariadenia

Dostane zariadenia vystavené riadiacej jednotke. Pre každé zariadenie je uvedený zoznam typov hodnôt (obsahujúci ID typu hodnoty a názov typu hodnoty). Niektoré z hodnôt môžu byť iba na čítanie (napr. Stav zariadenia).

Ak chcete nastaviť hodnoty zariadenia, musíte uviesť valueTypeId na identifikáciu vlastnosti zariadenia, ktorá bude nastavená.

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:

401 Neoprávnené
404 Nenašiel sa - umiestnenie nie je pripojené k cloudu
405 Metóda nie je povolená - dopyt alebo parametre sú neplatné
500 interná chyba servera

Získajte hodnotu zariadenia

Získava všetky aktuálne hodnoty pre dané zariadenie a ich typy. Hodnotové prvky pozostávajú z ID typu hodnoty, názvu typu hodnoty a skutočnej hodnoty. Niektoré z hodnôt môžu byť iba na čítanie (napr. Stav zariadenia).

Ak chcete nastaviť hodnoty zariadenia, musíte uviesť valueTypeId na identifikáciu vlastnosti zariadenia, ktorá bude nastavená.

Typ hodnoty je vždy číslo (dvojité).

Príliš častá požiadavka na rovnakú hodnotu (medzi požiadavkami menej ako 500 ms) môže namiesto načítania aktuálnej hodnoty z riadiacej jednotky namiesto uloženia aktuálnej hodnoty vrátiť hodnotu uloženú v pamäti. Odpovede s rovnakými poľami časových pečiatok sa týkajú rovnakej hodnoty. Nepredpokladajte, že hodnota časovej pečiatky stále rastie, mala by sa porovnávať iba kvôli rovnosti.

Variant 1
GET /api/CloudApi/v1/getDeviceValue/{deviceId}

Parametre: ID zariadenia v ceste adresy 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:

401 Neoprávnené
403 Zakázané - zariadenie nie je vystavené
404 Nenašiel sa - umiestnenie nie je pripojené k cloudu
405 Metóda nie je povolená - dopyt alebo parametre sú neplatné
500 Interná chyba servera

Získajte hodnoty z viacerých zariadení

Získa všetky aktuálne hodnoty pre dané zariadenia a ich typy. Prvky hodnoty odpovede pozostávajú 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 Core verziu 2021.3 alebo novšiu.

Zvážte získanie viacerých hodnôt naraz pomocou jedného volania rozhrania API, aby ste ušetrili šírku pásma a odoslali 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:

401 Neoprávnené
403 Zakázané - zariadenie nie je vystavené
404 Nenašiel sa - umiestnenie nie je pripojené k cloudu
405 Metóda nie je povolená - dopyt alebo parametre sú neplatné
500 Interná chyba servera

Získajte všetky hodnoty všetkých zariadení

Získa všetky aktuálne hodnoty všetkých zariadení naraz. Prvky hodnoty odpovede pozostávajú z id typu hodnoty, názvu typu hodnoty a skutočnej hodnoty. Niektoré hodnoty môžu byť len na čítanie (napr. Stav zariadenia). Táto funkcia vyžaduje Core verziu 2021.3 alebo novšiu.

Zvážte získanie viacerých hodnôt naraz pomocou jedného volania rozhrania API, aby ste ušetrili šírku pásma a odoslali 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:

401 Neoprávnené
403 Zakázané - zariadenie nie je vystavené
404 Nenašiel sa - umiestnenie nie je pripojené k cloudu
405 Metóda nie je povolená - dopyt alebo parametre sú neplatné
500 Interná chyba servera

Získajte hodnotu jedného zariadenia

Získa jednu aktuálnu hodnotu pre dané zariadenie a typ hodnoty ako text - nevyžaduje žiadne spracovanie JSON. Táto funkcia je ideálna pre jednoduché integrácie. Spravidla by ste tiež zahrnuli token do reťazca dotazu, takže všetky potrebné parametre sú uvedené v adrese URL a nastavenie hlavičiek HTTP nie je potrebné.

Odpoveď je vždy číslo (dvojité), naformátované na reťazec s desatinnou čiarkou a bez použitia tisícov oddeľovačov ani vedeckého zápisu. Ak je hodnota neznáma, odpoveď je NaN.

GET /api/CloudApi/v1/getOneDeviceValue/{deviceId}?valueTypeId={valueTypeId}&token={theToken}

Parametre: ID zariadenia v ceste adresy URL (napr. „1“) parametre dopytu - typ hodnoty typu (napr. „42“)

Príklad odpovede:

1.27

Možné chyby stavu HTTP:

401 Neoprávnené
403 Zakázané - zariadenie nie je vystavené
404 Nenašiel sa - umiestnenie nie je pripojené k cloudu
405 Metóda nie je povolená - dopyt alebo parametre sú neplatné
500 Interná chyba servera

Nastavte hodnotu zariadenia

Nastavuje jednu alebo viac hodnôt zariadenia s danými typmi. Hodnoty ostatných zariadení zostanú nedotknuté.

Typ hodnoty je vždy číslo (dvojité).

Príliš časté nastavenie rovnakej hodnoty (medzi požiadavkami menej ako 500 ms) 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 adresy URL (napr. „2“) parametre dotazu - až tri hodnoty a ich typy (napr. valueTypeId=46&hodnota=0,1&valueTypeId2=10&hodnota2=0,2)

Tento variant funkcie je ideálny pre jednoduché integrácie, nevyžaduje žiadne spracovanie JSON. Spravidla by ste tiež zahrnuli token do reťazca dotazu, takže všetky potrebné parametre sú uvedené v adrese URL a nastavenie hlavičiek HTTP 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:

401 Neoprávnené
403 Zakázané - zariadenie nie je vystavené
404 Nenašiel sa - umiestnenie nie je pripojené k cloudu
405 Metóda nie je povolená - dopyt alebo parametre sú neplatné
500 interná chyba servera
503 Služba nie je k dispozícii - príliš časté požiadavky na nastavenú hodnotu. Skúste to znova neskôr.

Chceme zlepšiť našu dokumentáciu

Vyplňte, prosím, krátky dotazník (1 minúta).