기기나 요청이 예상대로 작동하지 않는 경우 사용자에게 발생한 상황을 이해하고 가능하면 해결 방법을 알 수 있도록 적절한 오류 처리와 커뮤니케이션을 제공하는 것이 중요합니다. 가능한 실패 시나리오와 기기가 어떻게 응답해야 하는지 고려하세요. 사용자가 진행 중인 작업을 중단하면 어떻게 해야 하나요? 사용자가 기기가 오프라인 상태일 때 기기에서 작업을 요청하면 어떻게 되나요? 이러한 문제를 계획하고 사용자가 문제를 해결할 수 있도록 지원하면 사용자의 불만을 방지하고 기기에서 더 높은 품질의 환경을 제공할 수 있습니다.
이 가이드에서는 오류를 처리하는 인텐트 응답의 몇 가지 예를 제공합니다. 오류 및 예외에서 오류 및 예외에 유효한 errorCode 값을 검토하세요.
예 1: EXECUTE 인텐트의 오류 응답
최종 사용자가 거실에 스마트 조명 2개를 설치했습니다. 사용자가 '거실 조명 켜 줘'라는 명령어를 실행하면 Google에서 처리 URL로 EXECUTE 인텐트를 전송합니다. 사용자의 기기가 오프라인 상태이고 제어할 수 없는 것으로 확인되어 처리에서 status ERROR 및 errorCode deviceOffline가 포함된 EXECUTE 응답을 반환합니다.
이 예에서는 앞에서 설명한 대로 조명 기기에서 errorCode가 포함된 EXECUTE 응답을 반환하는 방법을 보여줍니다.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "light-device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "light-device-id-2" ], "status": "ERROR", "errorCode": "deviceOffline" } ] } }
Google Assistant는 응답을 수신한 후 사용자에게 '지금은 기기를 사용할 수 없습니다'라는 메시지를 표시합니다. EXECUTE 응답에서 errorCode deviceOffline를 전송한 후에도 여전히 보고 상태인 기기의 오프라인 상태를 전송해야 합니다.
예 2: EXECUTE 인텐트에 대한 비차단 예외
사용자가 Assistant를 사용하여 현관의 스마트 도어락을 잠그려고 합니다. 도어락을 제어할 수 있지만 기기 배터리가 부족한 것으로 확인되어 처리에서 status SUCCESS 및 exceptionCode lowBattery가 포함된 EXECUTE 응답을 반환합니다.
이 예에서는 앞에서 설명한 대로 도어락 기기에서 exceptionCode를 사용하여 EXECUTE 응답을 전송하는 방법을 보여줍니다.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["lock-device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
Assistant는 응답을 수신한 후 사용자에게 '기기의 배터리가 부족합니다'라는 메시지를 표시합니다.
예 3: 사전 오류 알림
경우에 따라 사용자에게 오류를 알리는 것이 좋습니다. 특히 사용자가 자동으로 완료될 것으로 예상하는 함수의 경우 더욱 그렇습니다. 사전 알림을 지원하는 트레잇의 경우 smart home 사전 알림을 구현한 경우 오류가 발생하는 동안 사용자에게 사전 알림을 보낼 수 있습니다.
스마트 건조기가 작동 중인데 누군가 주기가 끝나기 전에 문을 엽니다.
Google Home Graph API reportStateAndNotifications 메서드를 호출하여 errorCode를 사용하여 사전 알림을 보낼 수 있습니다.
이 예에서는 앞에서 설명한 대로 건조기 기기에서 errorCode를 사용하여 사전 알림을 보내는 방법을 보여줍니다.
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "dryer-device-id": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } }, "states": { "dryer-device-id": { "isRunning": false, "isPaused": true } } } } }
Assistant는 알림을 수신한 후 사용자에게 '기기 문이 열림'이라고 메시지를 표시합니다. 동일한 페이로드에서 알림과 함께 해당 기기 상태를 전송할 수 있습니다.
예 4: 후속 알림
후속 알림을 지원하는 트레잇 명령어의 경우 smart home 후속 알림을 구현한 경우 오류나 예외가 발생하는 동안 사용자에게 후속 알림을 보낼 수 있습니다.
사용자가 차고 문을 닫으라는 명령을 내렸으나 문이 닫히는 중에 걸립니다. errorCode를 사용하여 후속 알림을 보낼 수 있습니다.
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "door-device-id": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "follow-up-token-1" } } } }, "states": { "door-device-id": { "openPercent": 70 } } } } }
Assistant는 알림을 수신한 후 사용자에게 '기기가 걸림'이라고 메시지를 표시합니다. 동일한 페이로드에서 알림과 함께 상응하는 기기 상태를 전송할 수 있습니다.
자세한 내용과 errorCodes에 관한 자세한 내용은 오류 및 예외 참조 문서를 참고하세요.