Mengkueri dan mengeksekusi

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

Menangani intent QUERY

Respons QUERY Anda mencakup kumpulan status lengkap 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 intent QUERY.

Menangani intent EXECUTE

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

Gunakan Report State saat status perangkat pengguna berubah. Misalnya, karena intent EXECUTE atau perubahan status lokal (seperti mengalihkan tombol lampu secara manual). Tindakan ini membuat Google Home Graph tetap sinkron 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 informasi selengkapnya, lihat dokumentasi referensi intent 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 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 serta Error dan pengecualian untuk mengetahui detail selengkapnya.

Sebelumnya
Identifikasi dan sinkronisasi
Berikutnya
Putuskan sambungan