Abfrage und Ausführung

Wenn Nutzer mit Google Assistant interagieren, um den aktuellen Status eines Geräts abzufragen, wird an Ihre Auftragsausführung eine action.devices.QUERY-Intent mit einer Liste von Geräte-IDs gesendet (wie in Ihrer SYNC-Antwort angegeben). Ihre Ausführung erhält eine action.devices.EXECUTE-Intent, wenn Nutzer Assistant Befehle senden, um Ihr Gerät zu steuern.

QUERY-Intents verarbeiten

Die QUERY-Antwort enthält einen vollständigen Satz von Status für jedes der Merkmale, die von den angeforderten Geräten unterstützt werden.

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 Referenzdokumentation zur QUERY-Intent.

EXECUTE-Intents verarbeiten

Ähnlich wie bei QUERY kann eine einzelne Intent-Anfrage auf mehrere Geräte-IDs ausgerichtet sein. Eine einzelne EXECUTE-Intent kann auch mehrere unterschiedliche Befehle enthalten, die an eine Gruppe von Geräten gerichtet sind. So kann eine ausgelöste Absicht beispielsweise sowohl die Helligkeit als auch die Farbe einer Gruppe von Lampen festlegen oder mehrere Lampen jeweils auf eine andere Farbe setzen. Die EXECUTE-Antwort sollte den neuen Status des Geräts nach der Ausführung zurückgeben.

Verwende Report State, wenn sich der Status des Geräts des Nutzers ändert. Das kann beispielsweise aufgrund einer EXECUTE-Intention oder einer lokalen Statusänderung (z. B. manuelles Umschalten eines Lichtschalters) geschehen. So bleibt 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 Referenzdokumentation zu EXECUTE.

Statusantworten

Ihre QUERY- und EXECUTE-Antworten enthalten ein status-Feld, in dem das Ergebnis der Anfrage angegeben wird. 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 verknüpft.
  • ERROR: Die Anfrage ist mit dem entsprechenden errorCode fehlgeschlagen.

Weitere Informationen zu ERROR und EXCEPTIONS finden Sie unter Fehler und Ausnahmen behandeln und Fehler und Ausnahmen.

Zurück
Erkennen und synchronisieren
Weiter
Verbindung trennen