기기 또는 요청이 예상대로 작동하지 않으면 사용자에게 발생한 오류와 가능한 경우 문제를 해결하는 방법을 이해할 수 있도록 오류 처리와 커뮤니케이션을 올바르게 제공하는 것이 중요합니다. 발생 가능한 장애 시나리오와 기기의 응답 방식을 생각해 보세요. 사용자가 진행 중인 작업을 중단하면 어떻게 될까요? 사용자가 오프라인 상태일 때 기기에서 작업을 요청하면 어떻게 되나요? 이러한 문제를 계획하고 사용자가 문제에서 복구하도록 지원하면 사용자의 불만을 방지할 수 있으며 기기의 품질을 높일 수 있습니다.
이 가이드에서는 오류를 처리하는 인텐트 응답의 예를 제공합니다. 유효한 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 기기가 있는 기기를 사용해 현관문에 Smart Lock을 잠그려고 합니다. 개발자는 기기의 잠금을 성공적으로 제어할 수 있지만 기기 배터리가 부족하다는 사실을 알게 되면 처리에서 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은 오류 및 예외 참조 문서를 확인하세요.