오류 및 예외 처리

기기나 요청이 예상대로 작동하지 않는 경우 사용자에게 제대로 된 오류 처리 및 커뮤니케이션을 제공하여 발생한 문제와 가능한 경우 해결 방법을 파악하는 것이 중요합니다. 발생 가능한 오류 시나리오와 기기가 어떻게 응답할지 생각해야 합니다. 사용자가 진행 중인 작업을 중단하면 어떻게 될까요? 기기가 오프라인 상태일 때 사용자가 기기에서 작업을 요청하면 어떻게 될까요? 이러한 문제에 대비하고 사용자가 문제를 해결하도록 지원하면 사용자의 불만을 피할 수 있고 보다 우수한 기기 환경을 구축할 수 있습니다.

이 가이드에서는 오류를 처리하는 인텐트 응답의 몇 가지 예를 제공합니다. 오류 및 예외에 대한 유효한 errorCode 값을 검토하려면 오류 및 예외를 참조하세요.

예시 1: EXECUTE 인텐트의 오류 응답

최종 사용자가 2개의 스마트 조명을 거실에 설치했습니다. 사용자가 '거실 조명 켜기' 명령어를 실행하면 Google이 EXECUTE 인텐트를 처리 URL로 전송합니다. 사용자의 기기가 오프라인 상태이고 제어할 수 없으므로 처리에서 status ERRORerrorCode 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 SUCCESSexceptionCode lowBatteryEXECUTE 응답을 반환합니다.

이 예는 앞서 설명한 잠금 기기에서 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: 후속 조치 알림

후속 알림을 지원하는 trait 명령어의 경우 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에 대한 자세한 내용과 자세한 내용은 오류 및 예외 참조 문서를 확인하세요.