Chercher
MENU
  • Applications TapHome
  • Expressions
  • Architecture du système par type de projet
  • Utilisateurs et autorisations
  • API Cloud

    En utilisant API Cloud 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)

    Quel est le API Cloud?

    API Cloud 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 API Cloud peut être utilisé pratiquement pour n'importe quel langage de programmation.

    Les caractéristiques communes des ressources TapHome API Cloud sont les suivantes:

    • Vous accédez à la ressource en envoyant une requête HTTP au serveur TapHome API Cloud. Le serveur répond avec une réponse contenant les données que vous avez demandées

    • Toutes les ressources se trouvent sur ce site

    • Toutes les ressources peuvent renvoyer différents codes d'état HTTP (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

    • Une documentation swagger standard avec l'environnement de test est fournie sur ce site

    • Toutes les réponses sont au format Json et utilisent le codage de caractères UTF-8

    Authentification des API Cloud

    TapHome API Cloud 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 API Cloud 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 → API Cloud → 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.

    API Cloud 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

    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.