기기나 요청이 예상대로 작동하지 않는 경우 사용자에게 적절한 오류 처리와 커뮤니케이션을 제공하여 사용자가 발생한 상황을 이해하고 가능한 경우 해결 방법을 알 수 있도록 하는 것이 중요합니다. 발생 가능한 실패 시나리오와 기기가 어떻게 대응해야 하는지 충분히 고려해야 합니다. 사용자가 진행 중인 작업을 중단하면 어떻게 해야 할까요? 사용자가 기기가 오프라인 상태일 때 기기에서 작업을 요청하면 어떻게 되나요? 이러한 문제를 계획하고 사용자가 문제를 복구하도록 지원하면 사용자의 불만을 방지하고 기기에 더 높은 품질의 환경을 만들 수 있습니다.
이 가이드에서는 오류를 처리하는 인텐트 응답의 몇 가지 예를 제공합니다. 오류 및 예외를 참조하여 오류 및 예외에 대한 유효한 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는 오류 및 예외 참고 문서를 확인하세요.