쿼리 및 실행

사용자가 기기의 현재 상태를 쿼리하기 위해 Google Assistant와 상호작용하면 처리는 (SYNC 응답에 의해 제공된) 기기 ID 목록이 포함된 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의 자세한 내용은 오류 및 예외 처리와 오류 및 예외를 참조하세요.

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