Ricerca
MENU
  • Tap Home App
  • Espressioni
  • Architettura di sistema per tipo di progetto
  • Utenti e autorizzazioni
  • TapHome API

    Utilizzando TapHome API è possibile integrare i dispositivi TapHome in qualsiasi applicazione di terze parti. Ad esempio il controllo vocale di Apple Siri.

    Se sei interessato alla comunicazione diretta con l'unità di controllo all'interno di LAN o VPN, considera l'utilizzo

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

    Panoramica

    TapHome API definisce un insieme di funzioni a cui gli sviluppatori possono eseguire richieste e ricevere risposte. L'interazione viene eseguita tramite il protocollo HTTP. Un vantaggio di un tale approccio è l'ampio utilizzo di HTTP. Ecco perché TapHome API può essere utilizzato praticamente per qualsiasi linguaggio di programmazione.

    Panoramica di TapHome TapHome API:

    • Si accede alla risorsa inviando una richiesta HTTP al server TapHome TapHome API . Il server risponde con una risposta che contiene i dati richiesti
    • Tutte le risorse si trovano su https://cloudapi.taphome.com/api/cloudapi/v1/
    • Tutte le risorse possono restituire codici di stato HTTP diversi (ad esempio, codice di stato HTTP 200 per la risposta riuscita o codice di stato HTTP 400 per la richiesta errata)
    • Richiedi una risorsa particolare aggiungendo un percorso particolare all'URL di base che specifica la risorsa
    • Viene fornita la documentazione standard di swagger insieme all'ambiente di test
    • Tutte le risposte sono in formato Json e utilizzano la codifica dei caratteri UTF-8

    TapHome Core versione 2021.3 introduce una nuova funzionalità: TapHome API tramite rete locale. L'accesso a Core locale riduce la latenza di comunicazione e rende il sistema indipendente dalla connessione Internet. La specifica (autenticazione, richieste, risposte) è identica alla versione cloud. TapHome API sulla rete locale supporta solo il protocollo HTTP e non include l'interfaccia utente di Swagger.

    Autenticazione delle richieste di TapHome API

    TapHome TapHome API utilizza uno schema HTTP personalizzato basato su un'autenticazione di accesso di base. Non richiede cookie, identificatore di sessione né pagine di accesso. TapHome TapHome API tuttavia non utilizza la coppia login: password, ma un segreto condiviso chiamato token.

    L'intestazione HTTP di autenticazione personalizzata è formata come segue:

    Authorization: TapHome {token}

    Esempio di richiesta HTTP di autenticazione:

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

    Esempio utilizzando curl:

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

    Quando il sistema riceve una richiesta autenticata, recupera il token che si dichiara di avere e lo utilizza per identificare la posizione di un'unità di controllo TapHome. Se il token non corrisponde ai record TapHome, la richiesta viene ignorata e il sistema risponde con un messaggio di errore (in genere HTTP 401).

    In alternativa, è anche possibile inserire il token nei parametri di query (solo per chiamate HTTP GET). Si consiglia vivamente di non fornire tali URL a terzi in quanto il token potrebbe essere utilizzato per accedere e controllare qualsiasi dispositivo esposto dall'Unità di Controllo.

    Come ottenere il token

    Nell'app TapHome, vai su Impostazioni → Esponi dispositivi → TapHome API → Token. Facendo clic sulla freccia accanto al token Guid lo si copia negli appunti.

    Nel caso in cui il token sia stato compromesso e debba essere revocato, è possibile generare un nuovo token utilizzando l'app TapHome. C'è sempre un solo token attivo.

    TapHome API Riferimento

    Ottieni informazioni sulla posizione

    Ottiene le informazioni sulla posizione dell'unità di controllo. Usa questa chiamata per verificare se la posizione è online.

    Variant 1
    GET /api/CloudApi/v1/location

    Parametri: nessuno

    Variant 2
    POST /api/CloudApi/v1/location

    Parametri: nessuno

    Risposta di esempio:

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

    Possibili errori di stato HTTP:

    • 401 Non autorizzato

    • 404 Not Found: la posizione non è connessa al cloud

    • 405 Metodo non consentito: la query oi parametri non sono validi

    • 500 Errore interno del server

    Scopri i dispositivi

    Ottiene i dispositivi esposti dall'unità di controllo. Per ogni dispositivo viene fornito un elenco di tipi di valore (contenente id del tipo di valore e nome del tipo di valore). Alcuni dei valori possono essere di sola lettura (ad es. Stato dispositivo).

    Per impostare i valori del dispositivo è necessario fornire valueTypeId per identificare la proprietà del dispositivo che verrà impostata.

    Variant 1
    GET /api/CloudApi/v1/discovery

    Parametri: nessuno

    Variant 2
    POST /api/CloudApi/v1/discovery

    Parametri: nessuno

    Risposta di esempio:

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

    Possibili errori di stato HTTP:

    • 401 Non autorizzato

    • 404 Not Found: la posizione non è connessa al cloud

    • 405 Metodo non consentito: la query oi parametri non sono validi

    • 500 Errore interno del server

    Ottieni valore dispositivo

    Ottiene tutti i valori correnti per un determinato dispositivo e i relativi tipi. Gli elementi valore sono costituiti da tipo di valore id, nome del tipo di valore e valore effettivo. Alcuni dei valori possono essere di sola lettura (ad es. Stato dispositivo).

    Per impostare i valori del dispositivo è necessario fornire valueTypeId per identificare la proprietà del dispositivo che verrà impostata.

    Il tipo di valore è sempre un numero (doppio).

    Richiedere lo stesso valore troppo frequentemente (meno di 500 ms tra le richieste) può restituire un valore memorizzato nella cache invece di recuperare ogni volta il valore corrente dall'unità di controllo. Le risposte con campi timestamp uguali si riferiscono allo stesso valore. Non dare per scontato che il valore del timestamp sia sempre in crescita, dovrebbe essere confrontato solo per l'uguaglianza.

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

    Parametri: ID dispositivo nel percorso dell'URL (ad es. "1")

    Variant 2
    POST ​/api​/CloudApi​/v1​/getDeviceValue​

    Parametri:

    {
      "deviceId": 1
    }

    Risposta di esempio:

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

    Possibili errori di stato HTTP:

    • 401 Non autorizzato

    • 403 Vietato: il dispositivo non è esposto

    • 404 Not Found: la posizione non è connessa al cloud

    • 405 Metodo non consentito: la query oi parametri non sono validi

    • 500 Errore interno del server

    Ottieni i valori di più dispositivi

    Ottiene tutti i valori correnti per determinati dispositivi e i relativi tipi. Gli elementi del valore di risposta sono costituiti da ID tipo di valore, Nome tipo di valore e valore effettivo. Alcuni valori possono essere di sola lettura (es. Stato dispositivo). L'ID del tipo di valore è facoltativo. Questa funzione richiede Core versione 2021.3 o successiva.

    Prendi in considerazione la possibilità di ottenere più valori contemporaneamente con una singola chiamata per risparmiare larghezza di banda e inviare un numero ragionevole di richieste al server TapHome API


    POST ​/api​/CloudApi​/v1​/getMultipleDevicesValue​s

    Parametri:

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

    Risposta di esempio:

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

    Possibili errori di stato HTTP:

    • 401 Non autorizzato

    • 403 Vietato: il dispositivo non è esposto

    • 404 Not Found: la posizione non è connessa al cloud

    • 405 Metodo non consentito: la query oi parametri non sono validi

    • 500 Errore interno del server

    Ottieni tutti i valori di tutti i dispositivi

    Ottiene tutti i valori correnti di tutti i dispositivi contemporaneamente. Gli elementi del valore di risposta sono costituiti da un id del tipo di valore, un nome del tipo di valore e un valore effettivo. Alcuni valori possono essere di sola lettura (es. Stato dispositivo). Questa funzione richiede Core versione 2021.3 o successiva.

    Prendi in considerazione la possibilità di ottenere più valori contemporaneamente con una singola chiamata per risparmiare larghezza di banda e inviare un numero ragionevole di richieste al server TapHome API

    Variant 1
    GET ​/api​/CloudApi​/v1​/getAllDevicesValue​s

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

    Risposta di esempio:

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

    Possibili errori di stato HTTP:

    • 401 Non autorizzato

    • 403 Vietato: il dispositivo non è esposto

    • 404 Not Found: la posizione non è connessa al cloud

    • 405 Metodo non consentito: la query oi parametri non sono validi

    • 500 Errore interno del server

    Ottieni un valore per un dispositivo

    Ottiene un valore corrente per un determinato dispositivo e un tipo di valore id come testo: non richiede alcuna elaborazione JSON. Questa funzione è ideale per semplici integrazioni. In genere, includeresti anche il token nella stringa di query, quindi tutti i parametri necessari sono forniti nell'URL e l'impostazione delle intestazioni HTTP non è necessaria.

    La risposta è sempre un numero (doppio), formattato in stringa utilizzando il punto decimale e non utilizzando le migliaia di separatori né la notazione scientifica. Se il valore è sconosciuto, la risposta è NaN.

    Richiedere lo stesso valore troppo frequentemente (meno di 500 ms tra le richieste) può restituire un valore memorizzato nella cache invece di recuperare ogni volta il valore corrente dall'unità di controllo.

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

    Parametri: ID dispositivo nel percorso dell'URL (ad es. "1") parametri della query - ID tipo di valore (ad es. "42")

    Risposta di esempio:

    1.27

    Possibili errori di stato HTTP:

    • 401 Non autorizzato

    • 403 Vietato: il dispositivo non è esposto

    • 404 Not Found: la posizione non è connessa al cloud

    • 405 Metodo non consentito: la query oi parametri non sono validi

    • 500 Errore interno del server

    Imposta valore dispositivo

    Imposta uno o più valori di un dispositivo con determinati tipi. I valori degli altri dispositivi rimangono invariati.

    Il tipo di valore è sempre un numero (doppio).

    L'impostazione troppo frequente dello stesso valore (meno di 500 ms tra le richieste) genera un errore 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 dispositivo nel percorso dell'URL (ad es. "2") parametri di query: fino a tre valori e relativi tipi (ad es. valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)

    Questa variante di funzione è ideale per semplici integrazioni, non richiede alcuna elaborazione JSON. In genere, includeresti anche il token nella stringa di query, quindi tutti i parametri necessari sono forniti nell'URL e l'impostazione delle intestazioni HTTP non è necessaria.

    Variant 2
    POST /api/CloudApi/v1/setDeviceValue

    Parametri:

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

    Risposta di esempio:

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

    Possibili errori di stato HTTP:

    • 401 Non autorizzato

    • 403 Vietato: il dispositivo non è esposto

    • 404 Not Found: la posizione non è connessa al cloud

    • 405 Metodo non consentito: la query oi parametri non sono validi

    • 500 Errore interno del server

    • 503 Servizio non disponibile - richieste di valori impostati troppo frequenti. Riprovare più tardi.