Hľadaj
MENU
  • Aplikácie TapHome
  • Výrazy
  • Architektúra systému podľa typu projektu
  • Používatelia a povolenia
  • Cloud API

    Pomocou Cloud 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)

    Čo je Cloud API?

    Cloud 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é Cloud API použiť prakticky pre akýkoľvek programovací jazyk.

    TapHome Cloud API prehľad:

    • K prostriedku pristupujete odoslaním žiadosti HTTP na server TapHome Cloud API . Server odpovie odpoveďou, ktorá obsahuje údaje, ktoré ste požadovali
    • Všetky zdroje sa nachádzajú na https://cloudapi.taphome.com/api/cloudapi/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] (https://cloudapi.taphome.com/swagger)
    • Všetky odpovede sú vo formáte Json a používajú kódovanie znakov UTF-8

    Autentifikácia Cloud API požiadaviek

    TapHome Cloud 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 Cloud 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/cloudapi/v1/location HTTP/1.1
    Host: cloudapi.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://cloudapi.taphome.com/api/cloudapi/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 → Cloud API → Token. 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.

    Cloud 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/CloudApi/v1/location

    Parametre: žiadne

    Variant 2
    POST /api/CloudApi/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/CloudApi/v1/discovery

    Parametre: žiadne

    Variant 2
    POST /api/CloudApi/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 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.

    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.

    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/CloudApi/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/CloudApi/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.