오류 및 예외

이 문서에서는 스마트 홈 기기에서 공식적으로 지원되는 오류 및 예외를 나열합니다. 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가 생성됩니다.