Abfrage und Ausführung

Wenn Nutzer mit Google Assistant interagieren, um den aktuellen Status eines Geräts abzufragen, erhält die Auftragsausführung einen action.devices.QUERY-Intent, der eine Liste von Geräte-IDs enthält, wie in der Antwort von SYNC angegeben. Die Auftragsausführung empfängt einen action.devices.EXECUTE-Intent, wenn Nutzer Befehle an Assistant senden, um Ihr Gerät zu steuern.

QUERY-Intents verarbeiten

Ihre QUERY-Antwort enthält einen vollständigen Satz von Statuswerten für jede Eigenschaft, die von den angeforderten Geräten unterstützt wird.

Anfrage
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "foo"
          }
        }, {
          "id": "456",
          "customData": {
            "fooValue": 12,
            "barValue": false,
            "bazValue": "bar"
          }
        }]
      }
    }]
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true
      },
      "456": {
        "on": true,
        "online": true,
        "brightness": 80,
        "color": {
          "name": "cerulean",
          "spectrumRGB": 31655
        }
      }
    }
  }
}
Node.js
const {smarthome} = require('actions-on-google');
const app = smarthome();
// ...
app.onQuery((body, headers) => {
  // TODO Get device state
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          on: true,
          online: true
        },
        456: {
          on: true,
          online: true,
          brightness: 80,
          color: {
            name: "cerulean",
            spectrumRGB: 31655
          }
        }
      }
    }
  };
});
Java
@NotNull
@Override
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(
      new HashMap<String, Map<String, Object>>() {
        {
          put(
              "123",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                }
              });
          put(
              "456",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                  put("brightness", 80);
                  put(
                      "color",
                      new HashMap<String, Object>() {
                        {
                          put("name", "cerulean");
                          put("spectrumRGB", 31655);
                        }
                      });
                }
              });
        }
      });

  return new QueryResponse(queryRequest.getRequestId(), payload);
}

Weitere Informationen finden Sie in der Dokumentation zu QUERY-Intent-Referenzen.

EXECUTE-Intents verarbeiten

Ähnlich wie mit QUERY kann ein einzelner Intent auf mehrere Geräte-IDs ausgerichtet werden. Ein einzelner EXECUTE-Intent kann auch mehrere unterschiedliche Befehle enthalten, die einer Gruppe von Geräten zugewiesen werden. Ein ausgelöster Intent kann beispielsweise sowohl die Helligkeit als auch die Farbe für eine Gruppe von Lampen oder mehrere Lampen in einer anderen Farbe festlegen. Die EXECUTE-Antwort sollte nach der Ausführung den neuen Status des Geräts zurückgeben.

Verwenden Sie Report State, wenn sich der Status des Geräts des Nutzers ändert. Dies kann beispielsweise an einer EXECUTE-Absicht oder einer lokalen Statusänderung (z. B. manueller Umdrehen eines Lichtschalters) liegen. Dadurch wird Google Home Graph mit Ihrem Cloud-Dienst synchronisiert.

Anfrage
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123",
            "customData": {
              "fooValue": 74,
              "barValue": true,
              "bazValue": "sheepdip"
            }
          }, {
            "id": "456",
            "customData": {
              "fooValue": 36,
              "barValue": false,
              "bazValue": "moarsheep"
            }
          }],
          "execution": [{
            "command": "action.devices.commands.OnOff",
            "params": {
              "on": true
            }
          }]
        }]
      }
    }]
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      },
      {
        "ids": [
          "456"
        ],
        "status": "ERROR",
        "errorCode": "deviceTurnedOff"
      }
    ]
  }
}
Node.js
const {smarthome} = require('actions-on-google');
const app = smarthome();
// ...
app.onExecute((body, headers) => {
  // TODO Send command to device
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ["123"],
        status: "SUCCESS",
        states: {
          on: true,
          online: true
        }
      }, {
        ids: ["456"],
        status: "ERROR",
        errorCode: "deviceTurnedOff"
      }]
    }
  };
});
Java
@NotNull
@Override
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();

  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put("on", true);
                put("online", true);
              }
            },
            null,
            null),
        new Commands(new String[] {"456"}, "ERROR", null, "deviceTurnedOff", null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}

Weitere Informationen finden Sie in der Dokumentation zu EXECUTE-Intent-Referenzen.

Statusantworten

Ihre Antworten QUERY und EXECUTE enthalten das Feld status, um das Ergebnis der Anfrage zu melden. Jede Statusantwort kann einen der folgenden Werte enthalten:

  • SUCCESS: Die Anfrage war erfolgreich.
  • OFFLINE: Das Zielgerät ist offline oder anderweitig nicht erreichbar.
  • EXCEPTIONS: Mit der Anfrage ist ein Problem oder eine Benachrichtigung verbunden.
  • ERROR: Die Anfrage ist mit dem entsprechenden errorCode fehlgeschlagen.

Weitere Informationen zu ERROR und EXCEPTIONS finden Sie unter Umgang mit Fehlern und Ausnahmen sowie unter Fehler und Ausnahmen.

Zurück
Erkennen und synchronisieren
Weiter
Verbindung trennen