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://api.taphome.com/api/TapHomeApi/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/TapHomeApi/v1/location HTTP/1.1
Host: api.taphome.com
Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

Esempio utilizzando curl:

curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://api.taphome.com/api/TapHomeApi/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, andare su Impostazioni → Esponi dispositivi → TapHome API. Nel menu contestuale (tre punti in alto a destra), utilizzate la funzione Crea un nuovo token di accesso. Attenzione: ogni volta che si genera un nuovo token, i comandi URL originali smettono di funzionare. Fare clic sulla freccia accanto al token e la procedura guidata lo copierà negli appunti.

Nel caso in cui il token sia stato compromesso e debba essere revocato, è possibile generare un nuovo token utilizzando TapHome. Solo un token è sempre 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/TapHomeApi/v1/location

Parametri: nessuno

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

Parametri: nessuno

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

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.

Variant 1
GET /api/CloudApi/v1/getAllDevicesValues

Variant 2
POST /api/CloudApi/v1/getAllDevicesValues

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.

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