Chercher
MENU
  • Expressions / Langage de script
  • Utilisateurs et autorisations
  • Sauvegarde, restauration de sauvegarde, réinitialisation aux paramètres d'usine
  • TapHome API

    En utilisant TapHome API il est possible d'intégrer des appareils TapHome dans n'importe quelle application tierce. Par exemple, la commande vocale Apple Siri.

    Si vous êtes intéressé par une communication directe avec l'unité de contrôle au sein d'un LAN ou d'un VPN, veuillez envisager d'utiliser

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

    Aperçu

    TapHome API définit un ensemble de fonctions auxquelles les développeurs peuvent exécuter des requêtes et recevoir des réponses. L'interaction est effectuée via le protocole HTTP. Un avantage d'une telle approche est la large utilisation de HTTP. C'est pourquoi TapHome API peut être utilisé pratiquement pour n'importe quel langage de programmation.

    Présentation de TapHome TapHome API:

    • Vous accédez à la ressource en envoyant une requête HTTP au serveur TapHome TapHome API . Le serveur répond avec une réponse qui contient les données que vous avez demandées
    • Toutes les ressources se trouvent sur https://cloudapi.taphome.com/api/cloudapi/v1/
    • Toutes les ressources peuvent renvoyer des codes d'état HTTP différents (par exemple, le code d'état HTTP 200 pour une réponse réussie ou le code d'état HTTP 400 pour la mauvaise demande)
    • Vous demandez une ressource particulière en ajoutant un chemin particulier à l'URL de base qui spécifie la ressource
    • La documentation standard de swagger ainsi que l'environnement de test sont fournis
    • Toutes les réponses sont au format Json et utilisent l'encodage de caractères UTF-8

    TapHome Core version 201.3 introduit une nouvelle fonctionnalité : TapHome API via le réseau local. L'accès à Core localement diminue la latence de communication et rend le système indépendant de la connexion Internet. La spécification (authentification, requêtes, réponses) est identique à la version cloud. TapHome API sur le réseau local ne prend en charge que le protocole HTTP et n'inclut pas l'interface utilisateur Swagger.

    Authentification des TapHome API

    TapHome TapHome API utilise un schéma HTTP personnalisé basé sur une authentification d'accès de base. Il ne nécessite pas de cookies, d'identifiant de session ni de pages de connexion. TapHome TapHome API n'utilise cependant pas la paire login: password, mais un secret partagé appelé token.

    L'en-tête HTTP d'authentification personnalisée est formé comme suit:

    Authorization: TapHome {token}

    Exemple de requête HTTP d'authentification:

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

    Exemple utilisant curl:

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

    Lorsque le système reçoit une demande authentifiée, il récupère le jeton que vous prétendez avoir et l'utilise pour identifier un emplacement d'unité de contrôle TapHome. Si le jeton ne correspond pas aux enregistrements TapHome, la demande est abandonnée et le système répond avec un message d'erreur (généralement HTTP 401).

    Alternativement, il est également possible de placer le jeton dans les paramètres de requête (pour les appels HTTP GET uniquement). Nous vous suggérons fortement de ne pas fournir de telles URL à des tiers car le jeton peut être utilisé pour accéder et contrôler tout appareil exposé par l'unité de contrôle.

    Comment obtenir le jeton

    Dans l'application TapHome, accédez à Paramètres → Exposer les appareils → TapHome API → Token. Cliquez sur la flèche à côté du jeton Guid le copie dans le presse-papiers.

    Si le jeton a été compromis et doit être révoqué, un nouveau jeton peut être généré à l'aide de l'application TapHome. Il n'y a toujours qu'un seul jeton actif.

    TapHome API Référence

    Obtenir des informations de localisation

    Obtient les informations de localisation de l'unité de contrôle. Utilisez cet appel pour vérifier si l'emplacement est en ligne.

    Variant 1
    GET /api/CloudApi/v1/location

    Paramètres: aucun

    Variant 2
    POST /api/CloudApi/v1/location

    Paramètres: aucun

    Exemple de réponse:

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

    Erreurs d'état HTTP possibles:

    • 401 Non autorisé

    • 404 Not Found - l'emplacement n'est pas connecté au cloud

    • 405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides

    • 500 Erreur de serveur interne

    Découvrir les appareils

    Obtient les appareils exposés par l'unité de contrôle. Pour chaque périphérique, une liste de types de valeur est fournie (contenant l'identifiant du type de valeur et le nom du type de valeur). Certaines valeurs peuvent être en lecture seule (par exemple, l'état de l'appareil).

    Afin de définir les valeurs de périphérique, vous devez fournir le valueTypeId pour identifier la propriété de périphérique qui sera définie.

    Variant 1
    GET /api/CloudApi/v1/discovery

    Paramètres: aucun

    Variant 2
    POST /api/CloudApi/v1/discovery

    Paramètres: aucun

    Exemple de réponse:

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

    Erreurs d'état HTTP possibles:

    • 401 Non autorisé

    • 404 Not Found - l'emplacement n'est pas connecté au cloud

    • 405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides

    • 500 Erreur de serveur interne

    Obtenir la valeur de l'appareil

    Obtient toutes les valeurs actuelles pour un appareil donné et leurs types. Les éléments de valeur sont composés de l'identifiant du type de valeur, du nom du type de valeur et de la valeur réelle. Certaines des valeurs peuvent être en lecture seule (par exemple, l'état de l'appareil).

    Afin de définir les valeurs de périphérique, vous devez fournir le valueTypeId pour identifier la propriété de périphérique qui sera définie.

    Le type de valeur est toujours un nombre (double).

    Demander la même valeur trop fréquemment (moins de 500 ms entre les requêtes) peut renvoyer une valeur mise en cache au lieu de récupérer à chaque fois la valeur actuelle de l'unité de contrôle. Les réponses avec des champs d'horodatage égaux se réfèrent à la même valeur. Ne supposez pas que la valeur d'horodatage augmente constamment, elle doit être comparée uniquement pour l'égalité.

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

    Paramètres: identifiant de l'appareil dans le chemin de l'URL (par exemple, «1»)

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

    Paramètres:

    {
      "deviceId": 1
    }

    Exemple de réponse:

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

    Erreurs d'état HTTP possibles:

    • 401 Non autorisé

    • 403 Interdit - l'appareil n'est pas exposé

    • 404 Not Found - l'emplacement n'est pas connecté au cloud

    • 405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides

    • 500 Erreur de serveur interne

    Obtenir les valeurs de plusieurs appareils

    Obtient toutes les valeurs actuelles pour les appareils donnés et leurs types. Les éléments de valeur de réponse sont constitués de l'ID du type de valeur, du nom du type de valeur et de la valeur réelle. Certaines valeurs peuvent être en lecture seule (par exemple, État de l'appareil). L'ID du type de valeur est facultatif. Cette fonction nécessite Core version 201.3 ou plus récente.

    Envisagez d'obtenir plusieurs valeurs à la fois avec un seul appel d'API pour économiser de la bande passante et envoyer un nombre raisonnable de requêtes au serveur TapHome API


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

    Paramètres:

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

    Exemple de réponse:

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

    Erreurs d'état HTTP possibles:

    • 401 Non autorisé

    • 403 Interdit - l'appareil n'est pas exposé

    • 404 Not Found - l'emplacement n'est pas connecté au cloud

    • 405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides

    • 500 Erreur de serveur interne

    Obtenez toutes les valeurs de tous les appareils

    Obtient toutes les valeurs actuelles de tous les appareils à la fois. Les éléments de valeur de réponse se composent d'un identifiant de type de valeur, d'un nom de type de valeur et d'une valeur réelle. Certaines valeurs peuvent être en lecture seule (par exemple, État de l'appareil). Cette fonctionnalité nécessite Core version 201.3 ou ultérieure.

    Envisagez d'obtenir plusieurs valeurs à la fois avec un seul appel d'API pour économiser de la bande passante et envoyer un nombre raisonnable de requêtes au serveur TapHome API

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

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

    Exemple de réponse:

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

    Erreurs d'état HTTP possibles:

    • 401 Non autorisé

    • 403 Interdit - l'appareil n'est pas exposé

    • 404 Not Found - l'emplacement n'est pas connecté au cloud

    • 405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides

    • 500 Erreur de serveur interne

    Obtenez une valeur d'appareil

    Obtient une valeur actuelle pour un appareil donné et un identifiant de type de valeur sous forme de texte - il ne nécessite aucun traitement JSON. Cette fonction est idéale pour les intégrations simples. En règle générale, vous incluez également le jeton dans la chaîne de requête, de sorte que tous les paramètres nécessaires sont fournis dans l'URL et la définition des en-têtes HTTP n'est pas nécessaire.

    La réponse est toujours un nombre (double), formaté en chaîne en utilisant la virgule décimale et en n'utilisant aucun millier de séparateurs ni la notation scientifique. Si la valeur est inconnue, la réponse est NaN.

    Demander la même valeur trop fréquemment (moins de 500 ms entre les requêtes) peut renvoyer une valeur mise en cache au lieu de récupérer à chaque fois la valeur actuelle de l'unité de contrôle.

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

    Paramètres: identifiant de l'appareil dans le chemin de l'URL (par exemple, «1») paramètres de requête - id du type de valeur (par exemple «42»)

    Exemple de réponse:

    1.27

    Erreurs d'état HTTP possibles:

    • 401 Non autorisé

    • 403 Interdit - l'appareil n'est pas exposé

    • 404 Not Found - l'emplacement n'est pas connecté au cloud

    • 405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides

    • 500 Erreur de serveur interne

    Définir la valeur de l'appareil

    Définit une ou plusieurs valeurs d'un périphérique avec des types donnés. Les valeurs des autres appareils restent inchangées.

    Le type de valeur est toujours un nombre (double).

    La définition trop fréquente de la même valeur (moins de 500 ms entre les requêtes) entraîne une erreur HTTP 503.

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

    Paramètres: identifiant de l'appareil dans le chemin de l'URL (par exemple "2") paramètres de requête - jusqu'à trois valeurs et leurs types (par exemple valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)

    Cette variante de fonction est idéale pour les intégrations simples, elle ne nécessite aucun traitement JSON. En règle générale, vous incluez également le jeton dans la chaîne de requête, de sorte que tous les paramètres nécessaires sont fournis dans l'URL et la définition des en-têtes HTTP n'est pas nécessaire.

    Variant 2
    POST /api/CloudApi/v1/setDeviceValue

    Paramètres:

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

    Exemple de réponse:

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

    Erreurs d'état HTTP possibles:

    • 401 Non autorisé

    • 403 Interdit - l'appareil n'est pas exposé

    • 404 Not Found - l'emplacement n'est pas connecté au cloud

    • 405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides

    • 500 Erreur de serveur interne

    • 503 Service non disponible - demandes de valeur de consigne trop fréquentes. Réessayez plus tard.