Keresés
MENU
  • TapHome Apps
  • Kifejezések
  • Rendszer-architektúra projekttípusonként
  • Felhasználók és engedélyek
  • Cloud API

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

    Mi a Cloud API?

    Cloud 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 Cloud API gyakorlatilag bármely programozási nyelvhez használható.

    A TapHome Cloud API erőforrások közös jellemzői a következők:

    • Az erőforráshoz úgy férhet hozzá, hogy HTTP-kérést küld a TapHome Cloud API szerverre. A kiszolgáló válaszol, amely tartalmazza a kért adatokat

    • Az összes erőforrás [ezen a webhelyen] található (https://cloudapi.taphome.com/api/cloudapi/v1/)

    • 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ó URL-hez

    • A standard swagger dokumentáció és a tesztelési környezet együtt [ezen a webhelyen] található (https://cloudapi.taphome.com/swagger)

    • Minden válasz Json formátumban van, és az UTF-8 karakterkódolást használja

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

    A TapHome Cloud API alapértelmezett hozzáférési hitelesítésen alapuló egyéni HTTP-sémát használ. Nem igényel sütiket, munkamenet-azonosítót és bejelentkezési oldalakat. A TapHome Cloud API azonban nem a login: jelszó párost 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/cloudapi/v1/location HTTP/1.1
    Host: cloudapi.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://cloudapi.taphome.com/api/cloudapi/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 Cloud API → Cloud API → Token Cloud API . A token Guid melletti nyílra kattintva átmásolja a vágólapra.

    Abban az esetben, ha a tokent feltörték és visszavonni kell, akkor a TokHome alkalmazás segítségével új tokent lehet létrehozni. Mindig csak egy token aktív.

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

    Paraméterek: nincsenek

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

    Paraméterek: nincsenek

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

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