Suche
MENU
  • TapHome Apps
  • Ausdrücke
  • Systemarchitektur nach Projekttyp
  • Benutzer und Berechtigungen
  • Cloud-API

    Mit Cloud-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)

    Was ist die Cloud-API?

    Cloud-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 Cloud-API praktisch für jede Programmiersprache verwendet werden.

    Die allgemeinen Merkmale der TapHome-Ressourcen Cloud-API sind folgende:

    • Sie greifen auf die Ressource zu, indem Sie eine HTTP-Anforderung an den TapHome-Server Cloud-API. Der Server antwortet mit einer Antwort, die die von Ihnen angeforderten Daten enthält

    • Alle Ressourcen befinden sich auf dieser Site.

    • Alle Ressourcen geben möglicherweise unterschiedliche HTTP-Statuscodes zurück (z. B. HTTP-Statuscode 200 für eine erfolgreiche Antwort oder HTTP-Statuscode 400 für eine fehlerhafte Anforderung).

    • Sie fordern eine bestimmte Ressource an, indem Sie der Basis-URL, die die Ressource angibt, einen bestimmten Pfad hinzufügen

    • Standard-Swagger-Dokumentation zusammen mit der Testumgebung wird auf dieser Site bereitgestellt.

    • Alle Antworten sind im Json-Format und verwenden die UTF-8-Zeichencodierung

    Authentifizierung von Cloud-API Anfragen

    TapHome Cloud-API verwendet ein benutzerdefiniertes HTTP-Schema, das auf einer Cloud-API basiert. Es sind keine Cookies, Sitzungskennung oder Anmeldeseiten erforderlich. TapHome Cloud-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/cloudapi/v1/location HTTP/1.1
    Host: cloudapi.taphome.com
    Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

    Beispiel mit Curl:

    curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://cloudapi.taphome.com/api/cloudapi/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 verfügbar machen → Cloud-API → Token. Durch Klicken auf den Pfeil neben dem Token Guid wird dieser in die Zwischenablage kopiert.

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

    Cloud-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/CloudApi/v1/location

    Parameter: keine

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

    Parameter: keine

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

    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.

    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.

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