Keresés
MENU
  • Kifejezések / Szkriptnyelv
  • Felhasználók és engedélyek
  • Biztonsági mentés, biztonsági mentés visszaállítása, gyári beállítások visszaállítása
  • Software release notes
  • TapHome API

    A TapHome API használatával a TapHome eszközök integrálhatók bármely harmadik fél alkalmazásába. Például az Apple Siri hangvezérlés.

    Ha közvetlen kommunikációra kíváncsi a LAN vagy VPN vezérlőegységgel, akkor fontolja meg a használatát

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

    Áttekintés

    TapHome API meghatározza azon funkciók készletét, amelyekre a fejlesztők kéréseket hajthatnak végre és válaszokat fogadhatnak. Az interakciót a HTTP protokollon keresztül hajtják végre. Az ilyen megközelítés előnye a HTTP széleskörű használata. Ezért a TapHome API gyakorlatilag bármely programozási nyelvhez használható.

    TapHome TapHome API áttekintés:

    • Az erőforráshoz úgy férhet hozzá, hogy HTTP-kérést küld a TapHome TapHome API szerverre. A kiszolgáló válaszol, amely tartalmazza a kért adatokat
    • Az összes erőforrás a https://api.taphome.com/api/TapHomeApi/v1/ címen található.
    • Minden erőforrás különböző HTTP-állapotkódokat adhat vissza (pl. A 200-as HTTP-állapotkód a sikeres válaszra vagy a 400-as állapotkód a rossz kérésre)
    • Egy adott erőforrást úgy kér, hogy hozzáad egy adott elérési utat az erőforrást meghatározó alap URL-hez
    • A standard swagger dokumentáció a tesztelési környezettel együtt rendelkezésre áll
    • Minden válasz Json formátumban van, és az UTF-8 karakterkódolást használja

    A TapHome Core 2021.3 verziója új szolgáltatást vezet be: TapHome API helyi hálózaton keresztül. A Core helyi elérése csökkenti a kommunikációs késleltetést, és függetleníti a rendszert az internetkapcsolattól. A specifikáció (hitelesítés, kérések, válaszok) megegyezik a felhőverzióval. TapHome API a helyi hálózaton keresztül csak a HTTP protokollt támogatja, és nem tartalmazza a Swagger felhasználói felületet.

    Kérések hitelesítése TapHome API

    A TapHome TapHome API egyéni alapú HTTP -sémát használ, amely Basic access authentication alapú. Nem igényel cookie -kat, munkamenet -azonosítót és bejelentkezési oldalakat. A TapHome TapHome API azonban nem a bejelentkezési / jelszópárt használja, hanem a token nevű megosztott titkot.

    Egyéni hitelesítés A HTTP fejléc a következőképpen alakul:

    Authorization: TapHome {token}

    Példa a hitelesítés HTTP kérésére:

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

    Példa curl használatára:

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

    Amikor a rendszer hitelesített kérést kap, beolvassa az Ön által igényelt jogkivonatot, és felhasználja a TapHome vezérlőegység helyének azonosításához. Ha a token nem egyezik a TapHome rekordjaival, a kérés elvetésre kerül, és a rendszer hibaüzenettel válaszol (általában HTTP 401).

    Alternatív megoldásként a tokent is be lehet helyezni a lekérdezési paraméterekbe (csak a HTTP GET hívásokhoz). Erősen javasoljuk, hogy ne adjon meg ilyen URL-eket harmadik feleknek, mert a token felhasználható a Vezérlőegység által kitett eszközök elérésére és vezérlésére.

    Hogyan szerezzük meg a tokent

    A TapHome alkalmazásban lépjen a Beállítások → Eszközök feltárása → TapHome API menüpontra. A kontextusmenüben (három pont a jobb felső sarokban) használja a Hozzon létre új hozzáférési tokent funkciót. Vigyázat - amikor új tokent generál, az eredeti URL-parancsok nem működnek tovább. Kattintson a token melletti nyílra, és a varázsló átmásolja azt a vágólapra.

    Ha a token veszélybe került és vissza kell vonni, a TapHome segítségével új tokent lehet generálni. Mindig csak egy token aktív.

    TapHome API Hivatkozás

    Helyinformációk letöltése

    Megkapja a vezérlő helyének adatait. Ezzel a hívással ellenőrizheti, hogy a helyszín online-e.

    Variant 1
    GET /api/TapHomeApi/v1/location

    Paraméterek: nincsenek

    Variant 2
    POST /api/TapHomeApi/v1/location

    Paraméterek: nincsenek

    Példa válaszra:

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

    Lehetséges HTTP állapothibák:

    • 401 Jogosulatlan

    • 404 Nem található - a hely nem csatlakozik a felhőhöz

    • 405 A módszer nem engedélyezett - a lekérdezés vagy a paraméterek érvénytelenek

    • 500 Belső Szerver Hiba

    Fedezze fel az eszközöket

    Az eszközöket a Vezérlőegység teszi láthatóvá. Minden eszközhöz megadják az értéktípusok listáját (amely tartalmazza az értéktípus azonosítóját és az értéktípus nevét). Néhány érték csak olvasható (pl. Eszköz állapota).

    Az eszközértékek beállításához meg kell adnia a valueTypeId értéket a beállítandó eszköz tulajdonságának azonosításához.

    Variant 1
    GET /api/TapHomeApi/v1/discovery

    Paraméterek: nincsenek

    Variant 2
    POST /api/TapHomeApi/v1/discovery

    Paraméterek: nincsenek

    Példa válaszra:

    {
      "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
    }

    Lehetséges HTTP állapothibák:

    • 401 Jogosulatlan

    • 404 Nem található - a hely nem csatlakozik a felhőhöz

    • 405 A módszer nem engedélyezett - a lekérdezés vagy a paraméterek érvénytelenek

    • 500 Belső Szerver Hiba

    Eszközérték beolvasása

    Megkapja az adott eszköz összes típusát és típusát. Az értékelemek tartalmazzák az értéktípus azonosítóját, az értéktípus nevét és a tényleges értéket. Néhány érték csak olvasható (pl. Eszköz állapota).

    Az eszközértékek beállításához meg kell adnia a valueTypeId értéket a beállítandó eszköz tulajdonságának azonosításához.

    Az érték típusa mindig szám (dupla).

    Ha ugyanazt az értéket túl gyakran kéri (kevesebb, mint 500 ms a kérések között), akkor a gyorsítótárazott értéket adhatja vissza, ahelyett, hogy az aktuális értéket minden alkalommal lekérné a vezérlőegységről. Az azonos időbélyegzővel rendelkező válaszok ugyanarra az értékre utalnak. Ne feltételezzük, hogy az időbélyeg értéke mindig növekszik, csak az egyenlőség szempontjából kell összehasonlítani.

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

    Paraméterek: eszközazonosító az URL elérési útjában (pl. „1”)

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

    Paraméterek:

    {
      "deviceId": 1
    }

    Példa válaszra:

    {
      "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
    }

    Lehetséges HTTP állapothibák:

    • 401 Jogosulatlan

    • 403 Tilos - az eszköz nincs kitéve

    • 404 Nem található - a hely nem csatlakozik a felhőhöz

    • 405 A módszer nem engedélyezett - a lekérdezés vagy a paraméterek érvénytelenek

    • 500 Belső Szerver Hiba

    Több eszköz értékeinek lekérése

    Minden aktuális értéket lekér az adott eszközökre és azok típusaira. A válaszérték elemek az Értéktípus -azonosító, az Értéktípusnév és a tényleges értékekből állnak. Előfordulhat, hogy egyes értékek csak olvashatóak (pl. Eszközállapot). Az érték típusazonosító opcionális. Ehhez a funkcióhoz Core 2021.3 vagy újabb verzió szükséges.

    Fontolja meg, hogy egyszerre több értéket kapjon egyetlen API -hívással, hogy megtakarítsa a sávszélességet, és ésszerű számú kérést küldjön a TapHome API szervernek.


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

    Paraméterek:

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

    Példa válaszra:

    {
     "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
    }

    Lehetséges HTTP állapothibák:

    • 401 Jogosulatlan

    • 403 Tilos - az eszköz nincs kitéve

    • 404 Nem található - a hely nem csatlakozik a felhőhöz

    • 405 A módszer nem engedélyezett - a lekérdezés vagy a paraméterek érvénytelenek

    • 500 Belső Szerver Hiba

    Az összes eszköz összes értékének lekérése

    Egyszerre lekéri az összes eszköz összes aktuális értékét. A válaszérték elemek egy érték típusazonosítóból, egy értéktípusnévből és egy tényleges értékből állnak. Előfordulhat, hogy egyes értékek csak olvashatóak (pl. Eszközállapot). Ehhez a funkcióhoz Core 2021.3 vagy újabb verzió szükséges.

    Fontolja meg, hogy egyszerre több értéket kapjon egyetlen API -hívással, hogy megtakarítsa a sávszélességet, és ésszerű számú kérést küldjön a TapHome API szervernek.

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

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

    Példa válaszra:

    {
     "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
    }

    Lehetséges HTTP állapothibák:

    • 401 Jogosulatlan

    • 403 Tilos - az eszköz nincs kitéve

    • 404 Nem található - a hely nem csatlakozik a felhőhöz

    • 405 A módszer nem engedélyezett - a lekérdezés vagy a paraméterek érvénytelenek

    • 500 Belső Szerver Hiba

    Szerezzen be egy eszközértéket

    Egy aktuális értéket kap egy adott eszközhöz és az értéktípus azonosítóját szövegként - ez nem igényel JSON-feldolgozást. Ez a funkció ideális az egyszerű integrációkhoz. Általában a tokent is fel kell venni a lekérdezési karakterláncba, így az összes szükséges paraméter megadva az URL-ben, és a HTTP fejlécek beállítása nem szükséges.

    A válasz mindig szám (kettős), karakterláncra formázva tizedesvesszővel, ezer elválasztó és tudományos jelölés nélkül. Ha az érték ismeretlen, a válasz NaN.

    Ha ugyanazt az értéket túl gyakran kéri (kevesebb, mint 500 ms a kérések között), akkor egy gyorsítótárazott értéket adhat vissza, ahelyett, hogy az aktuális értéket minden alkalommal beolvasná a vezérlőegységből.

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

    Paraméterek: eszközazonosító az URL elérési útjában (pl. „1”) lekérdezési paraméterek - értéktípus azonosítója (pl. „42”)

    Példa válaszra:

    1.27

    Lehetséges HTTP állapothibák:

    • 401 Jogosulatlan

    • 403 Tilos - az eszköz nincs kitéve

    • 404 Nem található - a hely nem csatlakozik a felhőhöz

    • 405 A módszer nem engedélyezett - a lekérdezés vagy a paraméterek érvénytelenek

    • 500 Belső Szerver Hiba

    Eszközérték beállítása

    Egy vagy több értéket állít be egy adott típusú eszközhöz. Más eszközök értékei érintetlenül maradnak.

    Az érték típusa mindig szám (dupla).

    Ha ugyanazt az értéket túl gyakran (kevesebb, mint 500 ms a kérések között) állítja be, HTTP 503 hibát eredményez.

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

    Paraméterek: eszközazonosító az URL elérési útjában (pl. „2”) lekérdezési paraméterek - legfeljebb három érték és típusuk (pl. valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)

    Ez a funkcióváltozat ideális az egyszerű integrációkhoz, nem igényel JSON-feldolgozást. Általában a tokent is fel kell venni a lekérdezési karakterláncba, így az összes szükséges paraméter megadva az URL-ben, és a HTTP fejlécek beállítása nem szükséges.

    Variant 2
    POST /api/TapHomeApi/v1/setDeviceValue

    Paraméterek:

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

    Példa válaszra:

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

    Lehetséges HTTP állapothibák:

    • 401 Jogosulatlan

    • 403 Tilos - az eszköz nincs kitéve

    • 404 Nem található - a hely nem csatlakozik a felhőhöz

    • 405 A módszer nem engedélyezett - a lekérdezés vagy a paraméterek érvénytelenek

    • 500 Belső Szerver Hiba

    • 503 A szolgáltatás nem áll rendelkezésre - túl gyakori az alapértelmezett érték kérés. Próbáld újra később.