Empfang und Bestätigung von Befehlen

Grundlegender Ablauf der Befehlsintegration

Grundlegender Ablauf der Befehlsintegration

Das Gateway, Gerät oder der Endpunkt muss auf Befehle warten, indem die entsprechende Methode ausgeführt wird. Hierfür wird ein Long-Polling-Mechanismus verwendet, bei dem die Anfrage für eine definierte Zeitspanne auf der Serverseite verbleibt und mit der Antwort zurückkehrt, entweder wenn die angegebene Zeit abgelaufen ist oder wenn eine Befehlsausführung erkannt wurde.

Diese Antwort muss vom Gerät interpretiert werden, die entsprechenden Aktionen müssen durchgeführt werden, und eine Antwort muss über die Befehlsantwort-Methode gesendet werden, um zu melden, ob die Ausführung erfolgreich war oder nicht.

Bei Erfolg muss die Methode zur Aktualisierung des Gerätestatus entsprechend ausgeführt werden.

Stellen Sie abschließend sicher, dass das Warten auf Befehle mit der zuerst genannten Methode fortgesetzt wird.

1. Auf Befehle warten

Befehle können auf 3 Ebenen empfangen werden:

1. Auf Gateway-Ebene
2. Auf Geräte-Ebene
3. Auf Endpunkt-Ebene

Diese Befehle müssen zyklisch aufgerufen werden, um kontinuierlich auf ausgeführte Befehle zu warten.

Endpunkt-Befehle

Die WaitForCommand_Endpoint-Methode muss per HTTP POST aufgerufen werden:

POST /services/gear/DeviceIntegrationService.svc/WaitForCommand_Endpoint HTTP/1.1
Host: gear-dev.cloud.studio
Content-Type: application/json

{
    "accessToken": "",
    "endpointID": 1,
    "timeoutSeconds": 60
}

Parameter

Antwort

Die Antwort ist eine Liste innerhalb der WaitForCommand_EndpointResult-Eigenschaft, die jeden der entsprechenden Befehle enthält:

{
   "WaitForCommand_EndpointResult":[
      {
         "Closure":null,
         "CommandID":1120907993,
         "CommandType":1,
         "Custom":null,
         "DeviceID":7246,
         "Dimmer":null,
         "EndpointID":113139,
         "Management":null,
         "OnOff":{
            "AutomaticOverrideMinutes":0,
            "CommandType":1
         },
         "Thermostat":null
      }
   ]
}

Weitere Informationen zu den Antwort-Eigenschaften finden Sie in der Dokumentation.

Abhängig vom Typ des ausgeführten Befehls muss die entsprechende Eigenschaft berücksichtigt werden, um die durchzuführende Aktion zu bestimmen.

Wenn beispielsweise der CommandType 1 ist, bedeutet dies, dass es sich um einen Befehl für einen Endpunkt vom Typ "Appliance" handelt. Daher müssen die Informationen in der OnOff-Eigenschaft berücksichtigt werden.

Die verschiedenen Befehlstypen finden Sie in dieser Dokumentation.

2. Auf einen Befehl antworten

Wenn ein Befehl mit einer der WaitForCommands_*-Methoden empfangen wurde und nach Ausführung der entsprechenden Aktionen am Endpunkt (Hardware), muss auf den Befehl geantwortet werden, ob er erfolgreich war oder fehlgeschlagen ist.

Um zu melden, dass der Befehl ausgeführt wurde, rufen Sie die folgende Methode auf:

POST /services/gear/DeviceIntegrationService.svc/RespondCommand HTTP/1.1
Host: gear-dev.cloud.studio
Content-Type: application/json

{
    "accessToken": "",
    "response":{
        "CommandID": 1120907993,
        "ResponseType": 0,
        "ErrorCode": "",
        "ErrorMessage": "",
        "ResponseData": "ok"
    }
}

Die CommandID muss derjenigen entsprechen, die von der entsprechenden Befehlswarte-Methode erhalten wurde. Der ResponseType muss einer der Enum-Werte sein, je nach Bedarf. In diesem Fall ist es 0, was "Erfolg" bedeutet.

3. Endpunkt-Status aktualisieren

Wenn die Befehlsausführung erfolgreich war, muss der neue Endpunkt-Status gemeldet werden. Verwenden Sie hierfür die entsprechende Methode für den Endpunkt-Typ.

Dem Appliance-Beispiel folgend, rufen Sie die folgende Methode auf:

POST /services/gear/DeviceIntegrationService.svc/UpdateApplianceStatus HTTP/1.1
Host: gear-dev.cloud.studio
Content-Type: application/json

{
    "accessToken": "",
    "endpointID": 1,
    "isOn": true
}

Weitere Informationen zu dieser Methode finden Sie im Abschnitt Ein/Aus-Appliances.