오류 및 예외

이 문서에서는 스마트 홈 기기의 공식 지원 오류 및 예외를 나열합니다. 이러한 오류와 예외 코드를 인텐트 응답이나 알림에서 구현한 경우 Google 어시스턴트는 이를 사용하여 최종 사용자에게 지정된 명령어나 기기 상태와 관련된 문제를 알립니다. 응답에 잘못된 형식 또는 errorCode가 포함되어 있으면 Google 어시스턴트가 사용자에게 일반 오류 메시지(예: '죄송합니다. 현재 기기를 사용할 수 없습니다')와 같은 메시지를 표시합니다.

오류

문제로 인해 실행 또는 쿼리 요청이 실패하면 오류 코드를 반환해야 합니다. 예를 들어 문 잠금이 걸려 있어 잠그거나 잠금 해제할 수 없는 경우 이 상태에 관한 오류가 사용자에게 반환되어야 합니다.

오류 코드는 기기 수준 또는 전역 수준에서 연결할 수 있습니다. 예를 들어 한 제공업체의 조명이 많으며 허브에 의해 제어되는 경우 사용자가 조명을 모두 끄려고 할 때 제공업체는 기기 수준의 오류를 반환할 수 있습니다. 단일 조명이 오프라인이면 전체 수준의 오류를 반환하고 전체 허브가 오프라인 상태이고 조명을 제어할 수 없으면 전체 수준의 오류를 반환할 수 있습니다. 모든 기기가 오프라인 상태이더라도 전역 수준 오류와 기기 수준 오류에는 차이가 없습니다. 기기가 오프라인 상태이면 deviceOffline 오류 코드를 반환하더라도 reportState에서 {"online": false} 상태를 보고해야 합니다.

학습 내용을 요약하면 다음과 같습니다.

• 전역 수준 오류: 응답에 포함된 모든 기기에 동일한 오류가 있음
• 로컬 수준 오류: 응답 및 오류와 성공 사례의 혼합

전역 수준 오류

다음 JSON 스니펫은 QUERY 또는 EXECUTE 응답에서 전역 수준 오류를 반환하는 방법을 보여줍니다.

허브로 인한 전역 수준 오류 deviceOffline의 예시는 다음과 같습니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

허브로 인한 전역 수준 오류 inSoftwareUpdate의 예는 다음과 같습니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "inSoftwareUpdate",
    "status" : "ERROR"
  }
}

기기 수준 오류

QUERY 응답

다음 JSON 스니펫은 쿼리 응답에서 기기 수준 오류를 반환하는 방법을 보여줍니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

EXECUTE 응답

다음 JSON 스니펫은 EXECUTE 응답에서 기기 수준 오류를 반환하는 방법을 보여줍니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "device-id-2"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      }
    ]
  }
}

오류가 있는 알림

사전 알림

다음 JSON 스니펫은 사전 알림에서 기기 수준의 오류를 보고하는 방법을 보여줍니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

후속 응답

다음 JSON 스니펫은 후속 응답에서 기기 수준 오류를 보고하는 방법을 보여줍니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "PLACEHOLDER"
            }
          }
        }
      }
    }
  }
}

오류 목록

다음 오류는 기기에 연결된 TTS를 생성합니다.

예외

명령어와 관련된 문제 또는 알림이 있으면 예외를 반환해야 합니다. 명령어가 성공하거나 실패할 수 있습니다.

명령어가 성공하면 (상태 = 'SUCCESS') StatusReport 속성을 사용하거나 (대상 외 기기의 경우) 적절한 exceptionCode (대상 기기의 경우)를 반환하여 예외를 보고합니다.

예를 들어 건조기 린트 화면이 가득 찬 경우에도 사용자가 건조기를 시작할 수 있지만 이 상태에 관해 경고해야 할 수도 있습니다. 마찬가지로 기기의 배터리 잔량이 비어 있지 않아도 계속 명령어를 실행할 수 있지만 기기 배터리 잔량이 부족하다고 알려야 합니다.

예외로 인해 명령어가 실패하면 상태는 'EXCEPTIONS'여야 하며 예외는 StatusReport 특성을 사용하여 보고해야 합니다.

대상 기기에 관한 비차단 예외 (SUCCESS)

다음은 문을 잠그는 예입니다.

현관 잠금장치의 배터리가 부족합니다. 현관문을 잠급니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

StatusReport를 사용하는 다른 기기에 관한 비차단 예외 (SUCCESS)

이 예시는 보안 시스템을 설정합니다. 알겠습니다. 전면 창이 열려 있습니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isArmed": true,
        "currentArmLevel": "L2",
        "currentStatusReport": [{
          "blocking": false,
          "deviceTarget": "sensor_id1",
          "priority": 0,
          "statusCode": "deviceOpen"
        }]
      }
    }]
  }
}

StatusReport를 사용하여 다른 기기에 대한 예외 차단

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",
        "currentStatusReport": [{
            "blocking": true,
            "deviceTarget": "device-id-1",
            "priority": 0,
            "statusCode": "lowBattery"
          },
          {
            "blocking": true,
            "deviceTarget": "front_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "deviceTarget": "back_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          }
        ]
      }
    }
  }
}

예외 목록

다음 예외는 기기에서 연결된 TTS를 생성합니다.