스마트 홈 작업을 개발하는 방법을 알아볼 수 있는 새로운 공간인 Google Home 개발자 센터에 오신 것을 환영합니다. 참고: Actions 콘솔에서 작업을 계속 만들 수 있습니다.

오류 및 예외 처리

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

기기 또는 요청이 예상대로 작동하지 않으면 사용자에게 발생한 오류 처리 및 통신을 제공하여 발생한 문제 및 가능한 경우 문제 해결 방법을 파악하는 것이 중요합니다. 발생 가능한 장애 시나리오와 기기의 응답 방식을 생각해 보세요. 사용자가 진행 중인 작업을 중단하면 어떻게 될까요? 사용자가 오프라인 상태일 때 기기에서 작업을 요청하면 어떻게 되나요? 이러한 문제를 계획하고 사용자가 문제에서 복구하도록 지원하면 사용자의 불만을 방지할 수 있으며 기기의 품질을 개선할 수 있습니다.

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

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

최종 사용자에게 거실에 설치된 스마트 조명 2개가 설치되어 있습니다. 사용자가 '거실 조명 켜 줘' 명령어를 실행하면 Google은 처리 URL에 EXECUTE 인텐트를 전송했습니다. 사용자의 기기가 오프라인 상태이고 제어할 수 없는 것으로 확인되어 처리 과정에서 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 will prompt the user with "the device are not available right now" after receiving the response. Remember that you still need to send offline state for devices in report state after sending errorCode deviceOffline in EXECUTE response.

예 2: EXECUTE 인텐트의 비차단 예외

사용자가 Assistant 기기가 있는 기기를 사용하여 현관에 Smart Lock을 잠그려고 합니다. 개발자는 잠금을 성공적으로 제어할 수 있지만 기기 배터리가 부족할 때 처리에서 status SUCCESSexceptionCode lowBattery와 함께 EXECUTE 응답을 반환합니다.

이 예에서는 앞서 설명한 대로 잠금 기기에서 exceptionCodeEXECUTE 응답을 보내는 방법을 보여줍니다.

{
  "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 proactive notifications.를 구현한 경우 오류가 발생하는 동안 사용자에게 사전에 알릴 수 있습니다.

스마트 건조기가 작동 중이며, 생리 주기가 끝나기 전에 누군가 문을 열어줍니다. Google Home Graph API reportStateAndNotifications method to send a proactive notification with an 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오류 및 예외 참조 문서를 확인하세요.