쿼리 및 실행

사용자가 Google Assistant과 상호작용하여 기기의 현재 상태를 쿼리하면 처리에서 기기 ID 목록 (SYNC 응답에서 제공)이 포함된 action.devices.QUERY 인텐트를 수신합니다. 사용자가 Assistant에 명령을 보내 기기를 제어하면 주문 처리에서 action.devices.EXECUTE 인텐트를 수신합니다.

QUERY 인텐트 처리

QUERY 응답에는 요청된 기기에서 지원하는 각 특성의 전체 상태가 포함됩니다.

요청
{
    "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
          }
        }
      }
    }
  };
});
자바
@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);
}

자세한 내용은 QUERY 인텐트 참조 문서를 확인하세요.

EXECUTE 인텐트 처리

QUERY와 마찬가지로 단일 인텐트는 여러 기기 ID를 타겟팅할 수 있습니다. 단일 EXECUTE 인텐트에는 기기 그룹에 제공된 여러 개의 개별 명령어가 포함될 수도 있습니다. 예를 들어 트리거된 인텐트는 조명 그룹의 밝기와 색상을 모두 설정하거나 여러 조명을 각각 다른 색상으로 설정할 수 있습니다. EXECUTE 응답은 실행 후 기기의 새 상태를 반환해야 합니다.

사용자 기기의 상태가 변경되면 Report State를 사용합니다. 예를 들어 EXECUTE 인텐트 또는 로컬 상태 변경 (예: 전등 스위치를 수동으로 전환)으로 인해 이렇게 하면 Google Home Graph가 클라우드 서비스와 동기화된 상태로 유지됩니다.

요청
{
    "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"
      }]
    }
  };
});
자바
@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);
}

자세한 내용은 EXECUTE 인텐트 참조 문서를 확인하세요.

상태 응답

QUERY 및 EXECUTE 응답에는 요청 결과를 보고하는 status 필드가 포함됩니다. 각 상태 응답은 다음 값 중 하나를 제공할 수 있습니다.

  • SUCCESS: 요청이 성공했습니다.
  • OFFLINE: 타겟 기기가 오프라인이거나 연결할 수 없습니다.
  • EXCEPTIONS: 요청과 관련된 문제 또는 알림이 있습니다.
  • ERROR: 요청이 실패하고 해당 errorCode이 반환되었습니다.

ERROR 및 EXCEPTIONS의 경우 자세한 내용은 오류 및 예외 처리 및 오류 및 예외를 참고하세요.

이전
식별 및 동기화
다음
연결 해제