오류 및 예외

이 문서에는 스마트 홈 기기에 관해 공식적으로 지원되는 오류 및 예외 목록이 나와 있습니다. 주어진 오류 및 예외 코드를 인텐트 응답이나 알림(구현한 경우)에 사용하세요. 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가 생성됩니다.

예외

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

명령어가 성공하면 (status = "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가 생성됩니다.