Vyhledávání
MENU
  • TapHome Apps
  • Výrazy
  • Architektura systému podle typu projektu
  • Uživatelé a oprávnění
  • TapHome API

    Pomocí TapHome API je možné integrovat zařízení TapHome do jakékoli aplikace třetí strany. Například hlasové ovládání Apple Siri.

    Pokud máte zájem o přímou komunikaci s Řídicí jednotkou v rámci LAN nebo VPN, zvažte použití

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

    Přehled

    TapHome API definuje sadu funkcí, na které mohou vývojáři provádět požadavky a přijímat odpovědi. Interakce se provádí pomocí protokolu HTTP. Výhodou takového přístupu je široké využití HTTP. Proto lze TapHome API použít prakticky pro jakýkoli programovací jazyk.

    TapHome TapHome API přehled:

    • K prostředku přistupujete odesláním požadavku HTTP na server TapHome TapHome API . Server odpoví odpovědí, která obsahuje požadovaná data
    • Všechny zdroje se nacházejí na adrese https://cloudapi.taphome.com/api/cloudapi/v1/
    • Všechny zdroje mohou vracet různé stavové kódy HTTP (např. Stavový kód HTTP 200 pro úspěšnou odpověď nebo stavový kód HTTP 400 pro špatný požadavek)
    • Požadujete konkrétní zdroj přidáním konkrétní cesty k základní adrese URL, která specifikuje zdroj
    • Je poskytována standardní dokumentace swagger spolu s testovacím prostředím
    • Všechny odpovědi jsou ve formátu Json a používají kódování znaků UTF-8

    TapHome Core verze 2021.3 přináší novou funkci: TapHome API prostřednictvím místní sítě. Přístup k Core lokálně snižuje latenci komunikace a činí systém nezávislým na internetovém připojení. Specifikace (autentizace, požadavky, odpovědi) je identická s cloudovou verzí. TapHome API přes místní síť podporuje pouze protokol HTTP a neobsahuje uživatelské rozhraní Swagger.

    Ověřování TapHome API požadavků

    TapHome TapHome API používá vlastní schéma HTTP založené na základním ověřování přístupu. Nevyžaduje soubory cookie, identifikátor relace ani přihlašovací stránky. TapHome TapHome API však nepoužívá pár přihlášení: heslo, ale sdílené tajemství zvané token.

    Záhlaví vlastní autentizace HTTP je vytvořeno takto:

    Authorization: TapHome {token}

    Příklad požadavku ověřování HTTP:

    GET /api/cloudapi/v1/location HTTP/1.1
    Host: cloudapi.taphome.com
    Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

    Příklad použití curl:

    curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://cloudapi.taphome.com/api/cloudapi/v1/location"

    Když systém obdrží ověřený požadavek, načte token, který podle vás má, a použije ho k identifikaci umístění jednotky TapHome Control. Pokud token neodpovídá záznamům TapHome, požadavek je zrušen a systém odpoví chybovou zprávou (obvykle HTTP 401).

    Alternativně je také možné dát token do parametrů dotazu (pouze pro volání HTTP GET). Důrazně doporučujeme neposkytovat takové adresy URL třetím stranám, protože token lze použít k přístupu a ovládání jakéhokoli zařízení vystaveného řídicí jednotkou.

    Jak získat token

    V aplikaci TapHome přejděte do Nastavení → Vystavit zařízení → TapHome API → Token. Kliknutím na šipku vedle tokenu Guid jej zkopírujete do schránky.

    V případě, že token byl prolomen a musí být zrušen, lze nový token vygenerovat pomocí aplikace TapHome. Aktivní je vždy jen jeden token.

    TapHome API Reference

    Získejte informace o poloze

    Získá informace o poloze řídicí jednotky. Pomocí tyhle výzvy můžete zkontrolovat, zda je místo online.

    Variant 1
    GET /api/CloudApi/v1/location

    Parametry: žádné

    Variant 2
    POST /api/CloudApi/v1/location

    Parametry: žádné

    Příklad odpovědi:

    {
      "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b",
      "locationName": "Test Location",
      "timestamp": 855000000000
    }

    Možné chyby stavu HTTP:

    • 401 Neoprávněné

    • 404 Nenalezeno - umístění není připojeno ke cloudu

    • 405 Metoda není povolena - dotaz nebo parametry jsou neplatné

    • 500 interní chyba serveru

    Vyhledejte zařízení

    Získá zařízení vystavená řídicí jednotkou. U každého zařízení je uveden seznam typů hodnot (obsahující ID typu hodnoty a název typu hodnoty). Některé z hodnot mohou být pouze ke čtení (např. Stav zařízení).

    Chcete-li nastavit hodnoty zařízení, musíte zadat valueTypeId k identifikaci vlastnosti zařízení, která bude nastavena.

    Variant 1
    GET /api/CloudApi/v1/discovery

    Parametry: žádné

    Variant 2
    POST /api/CloudApi/v1/discovery

    Parametry: žádné

    Příklad odpovědi:

    {
      "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ávněné

    • 404 Nenalezeno - umístění není připojeno ke cloudu

    • 405 Metoda není povolena - dotaz nebo parametry jsou neplatné

    • 500 interní chyba serveru

    Získejte hodnotu zařízení

    Získá všechny aktuální hodnoty pro dané zařízení a jejich typy. Hodnotové prvky se skládají z ID typu hodnoty, názvu typu hodnoty a skutečné hodnoty. Některé z hodnot mohou být pouze ke čtení (např. Stav zařízení).

    Chcete-li nastavit hodnoty zařízení, musíte zadat valueTypeId k identifikaci vlastnosti zařízení, která bude nastavena.

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

    Příliš častý požadavek na stejnou hodnotu (méně než 500 ms mezi požadavky) může vrátit hodnotu uloženou v mezipaměti namísto načítání pokaždé, když aktuální hodnota z řídicí jednotky. Odpovědi se stejnými poli časových razítek odkazují na stejnou hodnotu. Nepředpokládejte, že hodnota časového razítka vždy roste, měla by být porovnávána pouze pro rovnost.

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

    Parametry: ID zařízení v cestě adresy URL (např. „1“)

    Variant 2
    POST ​/api​/CloudApi​/v1​/getDeviceValue​

    Parametry:

    {
      "deviceId": 1
    }

    Příklad odpovědi:

    {
      "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ávněné

    • 403 Zakázáno - zařízení není vystaveno

    • 404 Nenalezeno - umístění není připojeno ke cloudu

    • 405 Metoda není povolena - dotaz nebo parametry jsou neplatné

    • 500 interní chyba serveru

    Získejte hodnoty z více zařízení

    Získá všechny aktuální hodnoty pro daná zařízení a jejich typy. Prvky hodnoty odpovědi se skládají z ID typu hodnoty, názvu typu hodnoty a skutečné hodnoty. Některé hodnoty mohou být pouze pro čtení (např. Stav zařízení). ID typu hodnoty je volitelné. Tato funkce vyžaduje Core verze 2021.3 nebo novější.

    Zvažte získání více hodnot najednou pomocí jediného volání API, abyste ušetřili šířku pásma a odeslali přiměřený počet požadavků na server TapHome API


    POST ​/api​/CloudApi​/v1​/getMultipleDevicesValue​s

    Parametry:

    {
     "devices": [
        {
          "deviceId": 1,
          "valueTypeId": 7
        },
        {
          "deviceId": 2
        }
      ],
      "timestamp": 855000000000
    }

    Příklad odpovědi:

    {
     "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ávněné

    • 403 Zakázáno - zařízení není vystaveno

    • 404 Nenalezeno - umístění není připojeno ke cloudu

    • 405 Metoda není povolena - dotaz nebo parametry jsou neplatné

    • 500 interní chyba serveru

    Získejte všechny hodnoty všech zařízení

    Získá všechny aktuální hodnoty všech zařízení najednou. Prvky hodnoty odpovědi se skládají z id typu hodnoty, názvu typu hodnoty a skutečné hodnoty. Některé hodnoty mohou být pouze pro čtení (např. Stav zařízení). Tato funkce vyžaduje Core verze 2021.3 nebo novější.

    Zvažte získání více hodnot najednou pomocí jediného volání API, abyste ušetřili šířku pásma a odeslali přiměřený počet požadavků na server TapHome API

    Variant 1
    GET ​/api​/CloudApi​/v1​/getAllDevicesValue​s

    Variant 2
    POST ​/api​/CloudApi​/v1​/getAllDevicesValue​s

    Příklad odpovědi:

    {
     "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ávněné

    • 403 Zakázáno - zařízení není vystaveno

    • 404 Nenalezeno - umístění není připojeno ke cloudu

    • 405 Metoda není povolena - dotaz nebo parametry jsou neplatné

    • 500 interní chyba serveru

    Získejte jednu hodnotu zařízení

    Získá jednu aktuální hodnotu pro dané zařízení a typ hodnoty jako text - nevyžaduje žádné zpracování JSON. Tato funkce je ideální pro jednoduché integrace. Typicky byste také zahrnovali token do řetězce dotazu, takže všechny potřebné parametry jsou uvedeny v adrese URL a nastavení záhlaví HTTP není nutné.

    Odpověď je vždy číslo (dvojité), formátované na řetězec pomocí desetinné čárky a bez použití tisíců oddělovačů ani vědecké notace. Pokud je hodnota neznámá, odpověď je NaN.

    Příliš častý požadavek na stejnou hodnotu (méně než 500 ms mezi požadavky) může vrátit hodnotu uloženou v mezipaměti namísto načítání pokaždé, když aktuální hodnota z řídicí jednotky.

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

    Parametry: ID zařízení v cestě adresy URL (např. „1“) parametry dotazu - ID typu hodnoty (např. „42“)

    Příklad odpovědi:

    1.27

    Možné chyby stavu HTTP:

    • 401 Neoprávněné

    • 403 Zakázáno - zařízení není vystaveno

    • 404 Nenalezeno - umístění není připojeno ke cloudu

    • 405 Metoda není povolena - dotaz nebo parametry jsou neplatné

    • 500 interní chyba serveru

    Nastavte hodnotu zařízení

    Nastaví jednu nebo více hodnot zařízení s danými typy. Hodnoty ostatních zařízení zůstanou nedotčeny.

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

    Příliš časté nastavení stejné hodnoty (méně než 500 ms mezi požadavky) má za následek chybu HTTP 503.

    Variant 1
    GET /api/CloudApi/v1/setDeviceValue/{deviceId}?valueTypeId={valueTypeId1}&value={value1}&valueTypeId2={valueTypeId2}&value2={value2}&valueTypeId3={valueTypeId3}&value3={value3}&
    token={theToken}

    Parametry: ID zařízení v cestě adresy URL (např. „2“) parametry dotazu - až tři hodnoty a jejich typy (např. valueTypeId=46&value=0,1&valueTypeId2=10&value2 =0,2)

    Tato varianta funkce je ideální pro jednoduché integrace, nevyžaduje žádné zpracování JSON. Typicky byste také zahrnovali token do řetězce dotazu, takže všechny potřebné parametry jsou uvedeny v adrese URL a nastavení záhlaví HTTP není nutné.

    Variant 2
    POST /api/CloudApi/v1/setDeviceValue

    Parametry:

    {
      "deviceId": 2,
      "values": [
        {
          "valueTypeId": 46,
          "value": 0.1
        },
        {
          "valueTypeId": 10,
          "value": 0.2
        }
      ]
    }

    Příklad odpovědi:

    {
      "deviceId": 2,
      "valuesChanged": [
        {
          "typeId": 46,
          "result": "changed"
        },
        {
          "typeId": 10,
          "result": "notchanged"
        },
        {
          "typeId": 7,
          "result": "failed"
        }
      ],
      "timestamp": 855000000000
    }

    Možné chyby stavu HTTP:

    • 401 Neoprávněné

    • 403 Zakázáno - zařízení není vystaveno

    • 404 Nenalezeno - umístění není připojeno ke cloudu

    • 405 Metoda není povolena - dotaz nebo parametry jsou neplatné

    • 500 interní chyba serveru

    • 503 Služba není k dispozici - příliš časté požadavky na nastavenou hodnotu. Zkuste to později.