오류 및 예외

이 문서에서는 스마트 홈 기기에서 공식적으로 지원되는 오류 및 예외를 나열합니다. 이러한 오류와 예외 코드는 인텐트 응답 또는 알림(구현된 경우)에 사용하세요. 그러면 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 스니펫은 QUERY 응답에서 기기 수준 오류를 반환하는 방법을 보여줍니다.

{
  "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를 생성합니다.