Căutare
MENU
  • Atingeți Aplicații Acasă
  • Expressions
  • Arhitectura sistemului după tipul de proiect
  • Utilizatori și permisiuni
  • 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://cloudapi.taphome.com/api/cloudapi/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/cloudapi/v1/location HTTP/1.1
    Host: cloudapi.taphome.com
    Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

    Exemplu folosind curl:

    curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://cloudapi.taphome.com/api/cloudapi/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 Setări → Expune dispozitive → TapHome API → Token. Dacă faceți clic pe săgeata de lângă jetonul Guid o copiați în clipboard.

    În cazul în care simbolul a fost compromis și trebuie revocat, un nou simbol poate fi generat folosind aplicația TapHome. Există întotdeauna un singur simbol 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/CloudApi/v1/location

    Parametri: nici unul

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

    Parametri: nici unul

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

    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​/getAllDevicesValue​s

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

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