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

    Utilizzando API cloud è 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)

    Qual è il API cloud?

    API cloud 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é API cloud può essere utilizzato praticamente per qualsiasi linguaggio di programmazione.

    Le caratteristiche comuni delle risorse TapHome API cloud sono le seguenti:

    • Si accede alla risorsa inviando una richiesta HTTP al server TapHome API cloud . Il server risponde con una risposta che contiene i dati richiesti

    • Tutte le risorse si trovano [in questo sito] (https://cloudapi.taphome.com/api/cloudapi/v1/)

    • Tutte le risorse possono restituire diversi codici di stato HTTP (ad esempio, codice di stato HTTP 200 per la risposta di successo o codice di stato HTTP 400 per la richiesta non valida)

    • Richiedi una particolare risorsa aggiungendo un percorso particolare all'URL di base che specifica la risorsa

    • La documentazione standard di swagger insieme all'ambiente di test è fornita [in questo sito] (https://cloudapi.taphome.com/swagger)

    • Tutte le risposte sono in formato Json e utilizzano la codifica dei caratteri UTF-8

    Autenticazione delle richieste di API cloud

    TapHome API cloud utilizza uno schema HTTP personalizzato basato su un'autenticazione di accesso di base. Non richiede cookie, identificatore di sessione né pagine di accesso. TapHome API cloud 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 → API cloud → 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.

    API cloud 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 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.