Mengkueri dan mengeksekusi

Saat pengguna berinteraksi dengan Google Assistant untuk mengkueri status perangkat saat ini, fulfillment Anda akan menerima intent action.devices.QUERY yang berisi daftar ID perangkat (seperti yang diberikan oleh respons SYNC Anda). Pemenuhan Anda menerima maksud action.devices.EXECUTE saat pengguna mengirim perintah ke Assistant untuk mengontrol perangkat Anda.

Menangani intent QUERY

Respons QUERY Anda mencakup kumpulan lengkap status untuk setiap fitur yang didukung oleh perangkat yang diminta.

Permintaan
{
    "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);
}

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi maksud QUERY.

Menangani intent EXECUTE

Mirip dengan QUERY, satu maksud dapat menargetkan beberapa ID perangkat. Satu intent EXECUTE juga dapat berisi beberapa perintah berbeda yang diberikan ke grup perangkat. Misalnya, intent yang dipicu dapat menyetel kecerahan dan warna pada sekelompok lampu, atau menyetel setiap lampu ke warna yang berbeda. Respons EXECUTE Anda harus menampilkan status baru perangkat setelah eksekusi.

Gunakan Report State saat status perangkat pengguna berubah. Misalnya, karena maksud EXECUTE atau perubahan status lokal (seperti membalikkan sakelar lampu secara manual). Tindakan ini akan menjaga Google Home Graph tetap disinkronkan dengan layanan cloud Anda.

Permintaan
{
    "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);
}

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi maksud EXECUTE.

Respons status

Respons QUERY dan EXECUTE Anda menyertakan kolom status untuk melaporkan hasil permintaan. Setiap respons status dapat memberikan salah satu nilai berikut:

  • SUCCESS: Permintaan berhasil.
  • OFFLINE: Perangkat target sedang offline atau tidak dapat dijangkau.
  • EXCEPTIONS: Ada masalah atau pemberitahuan yang terkait dengan permintaan.
  • ERROR: Permintaan gagal dengan errorCode yang sesuai.

Untuk ERROR dan EXCEPTIONS, lihat Menangani error dan pengecualian dan Error dan pengecualian untuk mengetahui detail selengkapnya.

Sebelumnya
Identifikasi dan sinkronisasi
Berikutnya
Disconnect