TapHome API

Folosind TapHome API este posibilă integrarea dispozitivelor TapHome în orice aplicație terță parte. De exemplu, controlul vocal Apple Siri.

Dacă sunteți interesat de comunicarea directă cu unitatea de control din LAN sau VPN, vă rugăm să luați în considerare utilizarea

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

Prezentare generală

TapHome API definește un set de funcții la care dezvoltatorii pot efectua cereri și primi răspunsuri. Interacțiunea se realizează prin protocolul HTTP. Un avantaj al unei astfel de abordări este utilizarea pe scară largă a HTTP. De aceea TapHome API poate fi folosit practic pentru orice limbaj de programare.

TapHome TapHome API prezentare generală:

Accesați resursa trimițând o cerere HTTP către serverul TapHome TapHome API . Serverul răspunde cu un răspuns care conține datele pe care le-ați solicitat
Toate resursele sunt localizate la https://api.taphome.com/api/TapHomeApi/v1/
Toate resursele pot returna coduri de stare HTTP diferite (de exemplu, codul de stare HTTP 200 pentru răspunsul de succes sau codul de stare HTTP 400 pentru solicitarea greșită)
Solicitați o anumită resursă adăugând o anumită cale la adresa URL de bază care specifică resursa
Se furnizează documentația standard de swagger împreună cu mediul de testare
Toate răspunsurile sunt în format Json și utilizează codarea caracterelor UTF-8

TapHome Core versiunea 2021.3 introduce o nouă caracteristică: TapHome API prin rețeaua locală. Accesarea Core scade local latența comunicării și face sistemul independent de conexiunea la internet. Specificația (autentificare, solicitări, răspunsuri) este identică cu versiunea cloud. TapHome API în rețeaua locală acceptă doar protocolul HTTP și nu include interfața de utilizator Swagger.

Autentificarea TapHome API Solicitări

TapHome TapHome API utilizează o schemă HTTP personalizată bazată pe o autentificare de acces de bază. Nu necesită cookie-uri, identificator de sesiune și nici pagini de autentificare. Cu toate acestea, TapHome TapHome API nu utilizează perechea de autentificare: parolă, ci un secret comun numit token .

Antetul HTTP de autentificare personalizată este format după cum urmează:

Authorization: TapHome {token}

Exemplu de cerere HTTP de autentificare:

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

Exemplu folosind curl:

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

Când sistemul primește o solicitare autentificată, preia simbolul pe care pretindeți că îl deține și îl folosește pentru a identifica locația unității de control TapHome. Dacă simbolul nu se potrivește cu înregistrările TapHome, cererea este abandonată și sistemul răspunde cu un mesaj de eroare (de obicei HTTP 401).

Alternativ, este, de asemenea, posibil să introduceți simbolul în parametrii de interogare (numai pentru apelurile HTTP GET). Vă sugerăm insistent să nu furnizați astfel de adrese URL unor terțe părți, deoarece simbolul poate fi utilizat pentru a accesa și controla orice dispozitiv expus de unitatea de control.

Cum să obțineți jetonul

În aplicația TapHome, accesați Settings → Expose devices → TapHome API. În meniul contextual (cele trei puncte din dreapta sus), utilizați funcția Creați un nou token de acces. Atenție - de fiecare dată când generați un nou token, comenzile URL originale nu mai funcționează. Faceți clic pe săgeata din dreptul simbolului, iar expertul îl va copia în clipboard.

În cazul în care token-ul a fost compromis și trebuie revocat, se poate genera un nou token folosind TapHome. Doar un singur jeton este activ.

TapHome API Referință

Obțineți informații despre locație

Obține informații despre locația unității de control. Folosiți acest apel pentru a verifica dacă locația este online.

Variant 1
GET /api/TapHomeApi/v1/location

Parametri: nici unul

Variant 2
POST /api/TapHomeApi/v1/location

Parametri: nici unul

Exemplu de răspuns:

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

Posibile erori de stare HTTP:

401 Neautorizat
404 Not Found - locația nu este conectată la cloud
405 Metodă nepermisă - interogarea sau parametrii sunt nevalizi
500 Eroare internă a server-ului

Descoperiți dispozitive

Obține dispozitivele expuse de unitatea de control. Pentru fiecare dispozitiv este furnizată o listă de tipuri de valori (conținând tipul valorii id și numele tipului de valoare). Unele dintre valori pot fi doar în citire (de exemplu, Starea dispozitivului).

Pentru a seta valorile dispozitivului, trebuie să furnizați valueTypeId pentru a identifica proprietatea dispozitivului care va fi setată.

Variant 1
GET /api/TapHomeApi/v1/discovery

Parametri: nici unul

Variant 2
POST /api/TapHomeApi/v1/discovery

Parametri: nici unul

Exemplu de răspuns:

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

Posibile erori de stare HTTP:

401 Neautorizat
404 Not Found - locația nu este conectată la cloud
405 Metodă nepermisă - interogarea sau parametrii sunt nevalizi
500 Eroare internă a server-ului

Obțineți valoarea dispozitivului

Obține toate valorile actuale pentru un anumit dispozitiv și tipurile acestora. Elementele de valoare sunt compuse din tipul de valoare id, numele tipului de valoare și valoarea reală. Unele dintre valori pot fi doar în citire (de exemplu, Starea dispozitivului).

Pentru a seta valorile dispozitivului, trebuie să furnizați valueTypeId pentru a identifica proprietatea dispozitivului care va fi setată. Tipul valorii este întotdeauna un număr (dublu).

Solicitarea aceleiași valori prea frecvent (mai puțin de 500 ms între solicitări) poate returna o valoare cache, în loc să preia de fiecare dată valoarea curentă de la unitatea de control. Răspunsurile cu câmpuri de marcă de timp egale se referă la aceeași valoare. Nu presupuneți că valoarea marcajului de timp crește mereu, ar trebui comparată numai pentru egalitate.

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

Parametri: ID-ul dispozitivului în calea adresei URL (de exemplu, „1”)

Variant 2
POST /api/CloudApi/v1/getDeviceValue

Parametri:

{
  "deviceId": 1
}

Exemplu de răspuns:

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

Posibile erori de stare HTTP:

401 Neautorizat
403 Interzis - dispozitivul nu este expus
404 Not Found - locația nu este conectată la cloud
405 Metodă nepermisă - interogarea sau parametrii sunt nevalizi
500 Eroare internă a server-ului

Obțineți valori pentru mai multe dispozitive

Obține toate valorile actuale pentru dispozitivele date și tipurile lor. Elementele valorii răspunsului sunt alcătuite din ID tip valoare, nume tip valoare și valoarea reală. Unele valori pot fi doar în citire (de exemplu, Starea dispozitivului). ID tip valoare este opțional. Această funcție necesită Core versiunea 2021.3 sau mai recentă.

Luați în considerare obținerea mai multor valori simultan cu un singur apel API pentru a economisi lățimea de bandă și a trimite un număr rezonabil de solicitări către serverul TapHome API

POST /api/CloudApi/v1/getMultipleDevicesValues

Parametri:

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

Exemplu de răspuns:

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

Posibile erori de stare HTTP:

401 Neautorizat
403 Interzis - dispozitivul nu este expus
404 Not Found - locația nu este conectată la cloud
405 Metodă nepermisă - interogarea sau parametrii sunt nevalizi
500 Eroare internă a server-ului

Obțineți toate valorile tuturor dispozitivelor

Obține toate valorile actuale ale tuturor dispozitivelor simultan. Elementele valorii răspunsului constau dintr-un tip de valoare id, un nume de tip valoare și o valoare reală. Unele valori pot fi doar în citire (de exemplu, Starea dispozitivului). Această caracteristică necesită Core versiunea 2021.3 sau o versiune ulterioară.

Luați în considerare obținerea mai multor valori simultan cu un singur apel API pentru a economisi lățimea de bandă și a trimite un număr rezonabil de solicitări către serverul TapHome API

Variant 1
GET /api/CloudApi/v1/getAllDevicesValues

Variant 2
POST /api/CloudApi/v1/getAllDevicesValues

Exemplu de răspuns:

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

Posibile erori de stare HTTP:

401 Neautorizat
403 Interzis - dispozitivul nu este expus
404 Not Found - locația nu este conectată la cloud
405 Metodă nepermisă - interogarea sau parametrii sunt nevalizi
500 Eroare internă a server-ului

Obțineți o valoare de dispozitiv

Obține o valoare curentă pentru un dispozitiv dat și un tip de valoare id ca text - nu necesită nicio procesare JSON. Această funcție este ideală pentru integrări simple. De obicei, ați include și jetonul în șirul de interogare, astfel încât toți parametrii necesari sunt furnizați în adresa URL și setarea antetelor HTTP nu este necesară.

Răspunsul este întotdeauna un număr (dublu), formatat pe șir cu ajutorul punctului zecimal și fără a folosi mii de separatori și nici notația științifică. Dacă valoarea este necunoscută, răspunsul este NaN.

Solicitarea aceleiași valori prea frecvent (mai puțin de 500 ms între solicitări) poate returna o valoare cache, în loc să preia de fiecare dată valoarea curentă de la unitatea de control.

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

Parametri: ID-ul dispozitivului în calea adresei URL (de exemplu, „1”) parametrii de interogare - tipul valorii id (de ex. „42”)

Exemplu de răspuns:

1.27

Posibile erori de stare HTTP:

401 Neautorizat
403 Interzis - dispozitivul nu este expus
404 Not Found - locația nu este conectată la cloud
405 Metodă nepermisă - interogarea sau parametrii sunt nevalizi
500 Eroare internă a server-ului

Setați valoarea dispozitivului

Setează una sau mai multe valori ale unui dispozitiv cu tipuri date. Valorile altor dispozitive rămân neatinse.

Tipul valorii este întotdeauna un număr (dublu).

Setarea aceleiași valori prea frecvent (mai puțin de 500 ms între solicitări) duce la eroare HTTP 503.

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

Parametri: ID dispozitiv în calea adresei URL (de ex. „2”) parametrii de interogare - până la trei valori și tipurile lor (de ex. valueTypeId = 46 & value = 0.1 & valueTypeId2 = 10 & value2 = 0.2)

Această variantă de funcție este ideală pentru integrări simple, nu necesită nicio procesare JSON. De obicei, ați include și jetonul în șirul de interogare, astfel încât toți parametrii necesari sunt furnizați în adresa URL și setarea antetelor HTTP nu este necesară.

Variant 2
POST /api/TapHomeApi/v1/setDeviceValue

Parametri:

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

Exemplu de răspuns:

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

Posibile erori de stare HTTP:

401 Neautorizat
403 Interzis - dispozitivul nu este expus
404 Not Found - locația nu este conectată la cloud
405 Metodă nepermisă - interogarea sau parametrii sunt nevalizi
500 Eroare internă a server-ului
503 Serviciul nu este disponibil - solicitări de valoare set prea frecvente. Încercați mai târziu.