Eszközök megosztása

TapHome API

Integrálja a TapHome eszközöket alkalmazásokba HTTP és JSON használatával a TapHome API-n keresztül. Támogatja az autentikációt, az értékek lekérdezését és beállítását, webhookokat.

Áttekintés

A TapHome API lehetővé teszi a TapHome eszközök integrációját harmadik fél alkalmazásaiba HTTP-kérések és JSON-válaszok segítségével. A rendszer a https://api.taphome.com/api/TapHomeApi/v1/ címen érhető el.

Fő jellemzők:

  • HTTP-alapú erőforrás-hozzáférés megfelelő státuszkódokkal
  • Szabványos Swagger dokumentáció a https://api.taphome.com/api/doc címen
  • UTF-8 kódolású JSON válaszok
  • Helyi hálózati API-támogatás (Core 2021.3+) HTTP-n keresztül, Swagger UI nélkül

Helyi hálózati előnyök: A közvetlen LAN/VPN hozzáférés csökkenti a késleltetést és megszünteti az internetkapcsolattól való függést. A Core egységekhez fix IP-cím vagy mDNS-konfiguráció szükséges.

Hitelesítés

A TapHome API egyedi HTTP-alapú hitelesítést használ bearer tokenekkel (nem felhasználónév/jelszó-alapú hitelesítés).

Fejléc formátuma

1

Authorization: TapHome {token}

Példa kérés

1
2
3

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

cURL példa

1

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

Tokenkezelés

A tokenek a TapHome alkalmazásban, a Beállítások → Eszközök felfedése → TapHome API menüpontban érhetők el.

A kontextusmenüből (három pont) friss hozzáférési tokenek generálhatók. Új tokenok generálása érvényteleníti a korábbiakat. GET hívásokhoz lekérdezési paraméteres alternatíva is elérhető (biztonsági figyelmeztetés: kerülje a tokeneket tartalmazó URL-ek megosztását).

Kompromittált tokenek esetén azonnali regenerálás szükséges; egyszerre csak egy token lehet aktív.

API referencia

Helyinformáció lekérése

Lekéri a vezérlőegység helyadatait, és érvényesíti a kapcsolati állapotot.

Változat 1

1

GET /api/TapHomeApi/v1/location

Változat 2

1

POST /api/TapHomeApi/v1/location

Paraméterek: Nincs

Válasz:

1
2
3
4
5

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

HTTP állapot hibák:

  • 401 Nem hitelesített
  • 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz)
  • 405 Módszer nem engedélyezett
  • 500 Belső szerverhiba

Eszközök felfedezése

Lekéri a felfedett eszközöket és az általuk támogatott értéktípusokat, beleértve az írásvédett tulajdonságokat is, mint az Eszközállapot.

Változat 1

1

GET /api/TapHomeApi/v1/discovery

Változat 2

1

POST /api/TapHomeApi/v1/discovery

Paraméterek: Nincs

Válasz:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

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

HTTP állapot hibák:

  • 401 Nem hitelesített
  • 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz)
  • 405 Módszer nem engedélyezett
  • 500 Belső szerverhiba

Eszközérték lekérése

Lekéri egy adott eszköz összes aktuális értékét, beleértve a típusazonosítókat és neveket. Az értékek numerikusak (double típusúak). Néhány tulajdonság csak olvasható.

Gyakori kérések (500 ms alatti intervallumok) esetén előfordulhat, hogy gyorsítótárazott értékek kerülnek visszaadásra; az egyezőséget kizárólag az időbélyegek alapján ellenőrizze.

Változat 1

1

GET /api/CloudApi/v1/getDeviceValue/{deviceId}

Változat 2

1

POST /api/CloudApi/v1/getDeviceValue

Paraméterek: Eszközazonosító az URL-ben vagy a JSON törzsben

Válasz:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

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

HTTP állapot hibák:

  • 401 Nem hitelesített
  • 403 Tiltott (az eszköz nincs felfedve)
  • 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz)
  • 405 Módszer nem engedélyezett
  • 500 Belső szerverhiba

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

Egyszerre lekéri több eszköz aktuális értékeit. Csökkenti a sávszélesség-használatot az egyedi kérésekhez képest. Core 2021.3 vagy újabb verzió szükséges.

1

POST /api/CloudApi/v1/getMultipleDevicesValues

Paraméterek:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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

Válasz:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

HTTP állapot hibák:

  • 401 Nem hitelesített
  • 403 Tiltott (az eszköz nincs felfedve)
  • 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz)
  • 405 Módszer nem engedélyezett
  • 500 Belső szerverhiba

Az összes eszköz értékeinek lekérése

Egyszerre lekéri az összes előzetesen felfedett eszköz teljes állapotinformációját egyetlen kérésben. Core 2021.3 vagy újabb verzió szükséges.

Változat 1

1

GET /api/CloudApi/v1/getAllDevicesValues

Változat 2

1

POST /api/CloudApi/v1/getAllDevicesValues

Válasz:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

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

HTTP állapot hibák:

  • 401 Nem hitelesített
  • 403 Tiltott (az eszköz nincs felfedve)
  • 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz)
  • 405 Módszer nem engedélyezett
  • 500 Belső szerverhiba

Egy eszköz értékének lekérése

Lekéri egyetlen eszköz értékét JSON-feldolgozási követelmények nélkül. Ideális egyszerű megvalósításokhoz. A numerikus válasz (double) sztringként, tizedes ponttal formázva érkezik.

1

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

Paraméterek: Eszközazonosító az útvonalban, értéktípus-azonosító és token a lekérdezési paraméterekben

Válasz:

1

1.27

Ismeretlen értékek esetén NaN kerül visszaadásra. Gyakori kérések (500 ms alatti intervallumok) esetén előfordulhat, hogy gyorsítótárazott adatok kerülnek visszaadásra.

HTTP állapot hibák:

  • 401 Nem hitelesített
  • 403 Tiltott (az eszköz nincs felfedve)
  • 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz)
  • 405 Módszer nem engedélyezett
  • 500 Belső szerverhiba

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

Egy vagy több eszközérték módosítása típusazonosító alapján. A megadott értékek módosulnak, a meg nem adott értékek változatlanok maradnak. Numerikus típus (double).

Gyakori módosítások (500 ms alatti intervallumok) HTTP 503 választ eredményezhetnek.

Változat 1

1

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

Egyszerű használatra legfeljebb három egyidejű érték hozzárendelését támogatja.

Változat 2

1

POST /api/TapHomeApi/v1/setDeviceValue

Paraméterek:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

Válasz:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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

HTTP állapot hibák:

  • 401 Nem hitelesített
  • 403 Tiltott (az eszköz nincs felfedve)
  • 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz)
  • 405 Módszer nem engedélyezett
  • 500 Belső szerverhiba
  • 503 Szolgáltatás nem érhető el (túlzott értékállítási gyakoriság; próbálja újra később)

Webhook

A Webhook-funkcionalitás a nyilvános eszközállapot-változásokat HTTP POST kéréssel küldi egy konfigurált URL-re a helyi hálózatban vagy az interneten. Hatékonyabb szinkronizációt biztosít az időszakos lekérdezéshez képest.

Gátlás: Legalább 300 ms-os intervallumokkal aktiválódik. Gyors értékváltozások esetén csak a legutolsó módosulás kerül elküldésre; a korábbi köztes értékek elvetésre kerülnek. Sikertelen továbbítások nincsenek újrapróbálva.

Konfiguráció: A TapHome alkalmazás három egyedi HTTP kérésfejlécet támogat „kulcs: érték” formátumban.

Adatszerkezet: Meg egyezik a getMultipleDevicesValues végpont válaszformátumával.