Truy vấn và thực thi

Khi người dùng tương tác với Google Assistant để truy vấn trạng thái hiện tại của một thiết bị, yêu cầu thực hiện của bạn sẽ nhận được một ý định action.devices.QUERY chứa danh sách mã nhận dạng thiết bị (do phản hồi SYNC của bạn cung cấp). Phương thức thực hiện của bạn nhận được ý định action.devices.EXECUTE khi người dùng gửi lệnh đến Assistant để điều khiển thiết bị của bạn.

Xử lý ý định QUERY

Phản hồi QUERY của bạn bao gồm một bộ đầy đủ các trạng thái cho từng đặc điểm được các thiết bị được yêu cầu hỗ trợ.

Yêu cầu
{
    "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);
}

Để biết thêm thông tin, hãy xem tài liệu tham khảo về ý định QUERY.

Xử lý ý định EXECUTE

Tương tự như QUERY, một ý định duy nhất có thể nhắm đến nhiều mã thiết bị. Một ý định EXECUTE duy nhất cũng có thể chứa nhiều lệnh riêng biệt được đưa ra cho một nhóm thiết bị. Ví dụ: một ý định được kích hoạt có thể đặt cả độ sáng và màu sắc cho một nhóm đèn hoặc đặt nhiều đèn, mỗi đèn có một màu sắc khác nhau. Phản hồi EXECUTE của bạn sẽ trả về trạng thái mới của thiết bị sau khi thực thi.

Sử dụng Report State khi trạng thái của thiết bị người dùng thay đổi. Ví dụ: do một EXECUTEý định hoặc thay đổi trạng thái cục bộ (chẳng hạn như lật công tắc đèn theo cách thủ công). Thao tác này giúp Google Home Graph đồng bộ hoá với dịch vụ đám mây của bạn.

Yêu cầu
{
    "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);
}

Để biết thêm thông tin, hãy xem tài liệu tham khảo về ý định EXECUTE.

Phản hồi về trạng thái

Các phản hồi QUERY và EXECUTE của bạn bao gồm một trường status để báo cáo kết quả của yêu cầu. Mỗi phản hồi trạng thái có thể cung cấp một trong các giá trị sau:

  • SUCCESS: Yêu cầu thành công.
  • OFFLINE: Thiết bị mục tiêu đang ở chế độ ngoại tuyến hoặc không thể truy cập được.
  • EXCEPTIONS: Yêu cầu này có vấn đề hoặc cảnh báo.
  • ERROR: Yêu cầu không thành công với errorCode tương ứng.

Đối với ERROR và EXCEPTIONS, hãy xem bài viết Xử lý lỗi và ngoại lệ cũng như Lỗi và ngoại lệ để biết thêm thông tin chi tiết.

Trước
Xác định và đồng bộ hoá
Tiếp
Ngắt kết nối