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/getMultipleDevicesValues

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/getAllDevicesValues

Variant 2
POST /api/CloudApi/v1/getAllDevicesValues

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.