쿼리 및 실행

사용자가 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의 경우 자세한 내용은 오류 및 예외 처리 및 오류 및 예외를 참고하세요.

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