TapHome API

Mit TapHome API können TapHome-Geräte in jede Anwendung eines Drittanbieters integriert werden. Zum Beispiel Apple Siri Sprachsteuerung.

Wenn Sie an einer direkten Kommunikation mit der Steuereinheit innerhalb von LAN oder VPN interessiert sind, ziehen Sie bitte die Verwendung in Betracht

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

Überblick

TapHome API definiert eine Reihe von Funktionen, auf die die Entwickler Anforderungen ausführen und Antworten empfangen können. Die Interaktion erfolgt über das HTTP-Protokoll. Ein Vorteil eines solchen Ansatzes ist die breite Verwendung von HTTP. Deshalb kann TapHome API praktisch für jede Programmiersprache verwendet werden.

TapHome TapHome API Übersicht:

Sie greifen auf die Ressource zu, indem Sie eine HTTP-Anfrage an den TapHome-Server TapHome API . Der Server antwortet mit einer Antwort, die die von Ihnen angeforderten Daten enthält
Alle Ressourcen befinden sich unter https://api.taphome.com/api/TapHomeApi/v1/
Alle Ressourcen können unterschiedliche HTTP-Statuscodes zurückgeben (z. B. HTTP-Statuscode 200 für eine erfolgreiche Antwort oder HTTP-Statuscode 400 für die fehlerhafte Anfrage)
Sie fordern eine bestimmte Ressource an, indem Sie einen bestimmten Pfad zur Basis-URL hinzufügen, die die Ressource angibt
Standard-Swagger-Dokumentation zusammen mit Testumgebung wird bereitgestellt
Alle Antworten sind im Json-Format und verwenden die UTF-8-Zeichencodierung

TapHome Core Version 2021.3 führt eine neue Funktion ein: TapHome API über das lokale Netzwerk. Der lokale Zugriff auf Core verringert die Kommunikationslatenz und macht das System unabhängig von der Internetverbindung. Die Spezifikation (Authentifizierung, Anfragen, Antworten) ist identisch mit der Cloud-Version. TapHome API über das lokale Netzwerk unterstützt nur das HTTP-Protokoll und beinhaltet nicht die Swagger-Benutzeroberfläche.

Authentifizierung von TapHome API Anfragen

TapHome TapHome API verwendet ein benutzerdefiniertes HTTP-Schema basierend auf einer Basic Access Authentication. Es erfordert keine Cookies, Sitzungskennungen oder Anmeldeseiten. TapHome TapHome API jedoch kein Login/Passwort-Paar, sondern ein gemeinsames Geheimnis namens token.

Der HTTP-Header für die benutzerdefinierte Authentifizierung wird wie folgt gebildet:

Authorization: TapHome {token}

Beispiel für eine HTTP-Authentifizierungsanforderung:

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

Beispiel mit Curl:

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

Wenn das System eine authentifizierte Anforderung empfängt, ruft es das Token ab, das Sie angeblich haben, und verwendet es, um einen Standort der TapHome-Steuereinheit zu identifizieren. Wenn das Token nicht mit TapHome-Datensätzen übereinstimmt, wird die Anforderung gelöscht und das System antwortet mit einer Fehlermeldung (normalerweise HTTP 401).

Alternativ ist es auch möglich, das Token in die Abfrageparameter einzufügen (nur für HTTP-GET-Aufrufe). Wir empfehlen dringend, solche URLs nicht an Dritte weiterzugeben, da das Token für den Zugriff auf und die Steuerung von Geräten verwendet werden kann, die von der Steuereinheit verfügbar gemacht werden.

Wie bekomme ich den Token?

Gehen Sie in der TapHome-App zu Einstellungen → Geräte freigeben → TapHome API. Verwenden Sie im Kontextmenü (drei Punkte oben rechts) die Funktion Neues Zugriffstoken erstellen. Achtung: Wenn Sie ein neues Token erzeugen, funktionieren die ursprünglichen URL-Befehle nicht mehr. Klicken Sie auf den Pfeil neben dem Token und der Assistent kopiert es in die Zwischenablage.

Falls der Token kompromittiert wurde und widerrufen werden muss, kann mit TapHome ein neuer Token generiert werden. Es ist immer nur ein Token aktiv.

TapHome API Referenz

Standortinformationen abrufen

Ruft Informationen zum Standort der Steuereinheit ab. Verwenden Sie diesen Anruf, um zu überprüfen, ob der Standort online ist.

Variant 1
GET /api/TapHomeApi/v1/location

Parameter: keine

Variant 2
POST /api/TapHomeApi/v1/location

Parameter: keine

Beispielantwort:

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

Mögliche HTTP-Statusfehler:

401 nicht Autorisiert
404 Nicht gefunden - Der Standort ist nicht mit der Cloud verbunden
405 Methode nicht zulässig - Die Abfrage oder die Parameter sind ungültig
500 Interner Serverfehler

Geräte entdecken

Ruft Geräte ab, die von der Steuereinheit freigelegt wurden. Für jedes Gerät wird eine Liste von Werttypen bereitgestellt (mit Werttyp-ID und Werttypname). Einige der Werte sind möglicherweise schreibgeschützt (z. B. Gerätestatus).

Um Gerätewerte festzulegen, müssen Sie die valueTypeId angeben, um die Geräteeigenschaft zu identifizieren, die festgelegt werden soll.

Variant 1
GET /api/TapHomeApi/v1/discovery

Parameter: keine

Variant 2
POST /api/TapHomeApi/v1/discovery

Parameter: keine

Beispielantwort:

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

Mögliche HTTP-Statusfehler:

401 nicht Autorisiert
404 Nicht gefunden - Der Standort ist nicht mit der Cloud verbunden
405 Methode nicht zulässig - Die Abfrage oder die Parameter sind ungültig
500 Interner Serverfehler

Gerätewert abrufen

Ruft alle aktuellen Werte für ein bestimmtes Gerät und deren Typen ab. Die Wertelemente bestehen aus der Werttyp-ID, dem Werttypnamen und dem tatsächlichen Wert. Einige der Werte sind möglicherweise schreibgeschützt (z. B. Gerätestatus).

Um Gerätewerte festzulegen, müssen Sie die valueTypeId angeben, um die Geräteeigenschaft zu identifizieren, die festgelegt werden soll.

Der Werttyp ist immer eine Zahl (doppelt).

Wenn Sie denselben Wert zu häufig anfordern (weniger als 500 ms zwischen den Anforderungen), wird möglicherweise ein zwischengespeicherter Wert zurückgegeben, anstatt jedes Mal den aktuellen Wert von der Steuereinheit abzurufen. Antworten mit gleichen Zeitstempelfeldern beziehen sich auf denselben Wert. Nehmen Sie nicht an, dass der Zeitstempelwert immer wächst, er sollte nur auf Gleichheit verglichen werden.

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

Parameter: Geräte-ID im URL-Pfad (z. B. "1")

Variant 2
POST /api/CloudApi/v1/getDeviceValue

Parameter:

{
  "deviceId": 1
}

Beispielantwort:

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

Mögliche HTTP-Statusfehler:

401 nicht Autorisiert
403 Verboten - Das Gerät ist nicht ausgesetzt
404 Nicht gefunden - Der Standort ist nicht mit der Cloud verbunden
405 Methode nicht zulässig - Die Abfrage oder die Parameter sind ungültig
500 Interner Serverfehler

Werte von mehreren Geräten abrufen

Ruft alle aktuellen Werte für bestimmte Geräte und deren Typen ab. Die Antwortwertelemente bestehen aus der Werttyp-ID, dem Werttypnamen und dem Istwert. Einige Werte können schreibgeschützt sein (zB Gerätestatus). Die Werttyp-ID ist optional. Diese Funktion erfordert Core Version 2021.3 oder neuer.

Ziehen Sie in Betracht, mehrere Werte gleichzeitig mit einem einzigen API-Aufruf abzurufen, um Bandbreite zu sparen und eine angemessene Anzahl von Anfragen an den Server TapHome API

POST /api/CloudApi/v1/getMultipleDevicesValues

Parameter:

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

Beispielantwort:

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

Mögliche HTTP-Statusfehler:

401 nicht Autorisiert
403 Verboten - Das Gerät ist nicht ausgesetzt
404 Nicht gefunden - Der Standort ist nicht mit der Cloud verbunden
405 Methode nicht zulässig - Die Abfrage oder die Parameter sind ungültig
500 Interner Serverfehler

Holen Sie sich alle Werte aller Geräte

Ruft alle aktuellen Werte aller Geräte auf einmal ab. Die Antwortwertelemente bestehen aus einer Werttyp-ID, einem Werttypnamen und einem Istwert. Einige Werte können schreibgeschützt sein (zB Gerätestatus). Diese Funktion erfordert Core Version 2021.3 oder höher.

Ziehen Sie in Betracht, mehrere Werte gleichzeitig mit einem einzigen API-Aufruf abzurufen, um Bandbreite zu sparen und eine angemessene Anzahl von Anfragen an den Server TapHome API

Variant 1
GET /api/CloudApi/v1/getAllDevicesValues

Variant 2
POST /api/CloudApi/v1/getAllDevicesValues

Beispielantwort:

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

Mögliche HTTP-Statusfehler:

401 nicht Autorisiert
403 Verboten - Das Gerät ist nicht ausgesetzt
404 Nicht gefunden - Der Standort ist nicht mit der Cloud verbunden
405 Methode nicht zulässig - Die Abfrage oder die Parameter sind ungültig
500 Interner Serverfehler

Holen Sie sich einen Gerätewert

Ruft einen aktuellen Wert für ein bestimmtes Gerät und eine Werttyp-ID als Text ab. Es ist keine JSON-Verarbeitung erforderlich. Diese Funktion ist ideal für einfache Integrationen. In der Regel wird das Token auch in die Abfragezeichenfolge aufgenommen, sodass alle erforderlichen Parameter in der URL angegeben sind und das Festlegen der HTTP-Header nicht erforderlich ist.

Die Antwort ist immer eine Zahl (doppelt), die mit einem Dezimalpunkt als Zeichenfolge formatiert ist und weder tausend Trennzeichen noch die wissenschaftliche Notation verwendet. Wenn der Wert unbekannt ist, lautet die Antwort NaN.

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

Parameter: Geräte-ID im URL-Pfad (z. B. "1") Abfrageparameter - Werttyp-ID (z. B. "42")

Beispielantwort:

1.27

Mögliche HTTP-Statusfehler:

401 nicht Autorisiert
403 Verboten - Das Gerät ist nicht ausgesetzt
404 Nicht gefunden - Der Standort ist nicht mit der Cloud verbunden
405 Methode nicht zulässig - Die Abfrage oder die Parameter sind ungültig
500 Interner Serverfehler

Gerätewert einstellen

Legt einen oder mehrere Werte eines Geräts mit bestimmten Typen fest. Die Werte anderer Geräte bleiben unberührt.

Der Werttyp ist immer eine Zahl (doppelt).

Wenn Sie den gleichen Wert zu häufig einstellen (weniger als 500 ms zwischen den Anforderungen), tritt ein HTTP 503-Fehler auf.

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

Parameter: Geräte-ID im URL-Pfad (z. B. "2") Abfrageparameter - bis zu drei Werte und ihre Typen (z. B. valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)

Diese Funktionsvariante ist ideal für einfache Integrationen, sie erfordert keine JSON-Verarbeitung. In der Regel wird das Token auch in die Abfragezeichenfolge aufgenommen, sodass alle erforderlichen Parameter in der URL angegeben sind und das Festlegen der HTTP-Header nicht erforderlich ist.

Variant 2
POST /api/TapHomeApi/v1/setDeviceValue

Parameter:

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

Beispielantwort:

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

Mögliche HTTP-Statusfehler:

401 nicht Autorisiert
403 Verboten - Das Gerät ist nicht ausgesetzt
404 Nicht gefunden - Der Standort ist nicht mit der Cloud verbunden
405 Methode nicht zulässig - Die Abfrage oder die Parameter sind ungültig
500 Interner Serverfehler
503 Service nicht verfügbar - zu häufige Sollwertanforderungen. Versuchen Sie es später erneut.