Błędy i wyjątki

Ten dokument zawiera oficjalnie obsługiwane błędy i wyjątki dotyczące inteligentnych urządzeń domowych. Tych kodów błędów i wyjątków używaj w odpowiedzi intencji lub w powiadomieniach, jeśli została zaimplementowana. Dzięki temu Asystent Google będzie ostrzegać użytkowników o problemach związanych z danym poleceniem lub stanem urządzenia. Jeśli odpowiedź zawiera nieprawidłowe formatowanie lub atrybut errorCode, Asystent Google wyświetla użytkownikom ogólny komunikat o błędzie, na przykład „Urządzenie urządzenie jest teraz niedostępne”.

Błędy

Kod błędu powinien być zwracany, gdy wykonanie problemu powoduje błąd wykonania lub żądania zapytania. Jeśli np. zamek w drzwiach się zaciął i nie można go zamknąć ani odblokować, użytkownik powinien otrzymać komunikat o błędzie dotyczący tego stanu.

Kody błędów można dołączać na poziomie urządzenia lub na poziomie globalnym. Jeśli na przykład użytkownik ma wiele punktów oświetlenia od jednego dostawcy i jest sterowany przez centralę, to gdy użytkownik poprosi o wyłączenie wszystkich świateł, dostawca może zwrócić błąd na poziomie urządzenia, gdy pojedynczy punkt oświetlenia jest offline, lub błąd globalny, jeśli całe centrum jest offline i nie można sterować oświetleniem. Jeśli wszystkie urządzenia są offline, nie ma różnicy między używaniem błędów na poziomie globalnym i na poziomie urządzenia. Jeśli urządzenie jest offline, stan {"online": false} należy zgłosić w parametrze reportState nawet wtedy, gdy zwracany jest kod błędu deviceOffline.

W skrócie:

• Błąd na poziomie globalnym: wszystkie urządzenia w odpowiedzi mają ten sam błąd.
• Błąd na poziomie lokalnym: odpowiedź mieszana z błędami i przypadkami powodzenia

Błędy na poziomie globalnym

Poniższy fragment kodu JSON pokazuje, jak zwracasz błędy na poziomie globalnym w odpowiedzi QUERY lub EXECUTE.

Przykład błędu na poziomie globalnym deviceOffline spowodowany przez centrum:

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

Przykład błędu na poziomie globalnym inSoftwareUpdate spowodowany aktualizowaniem centrum:

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

Błędy na poziomie urządzenia

Odpowiedź QUERY

Poniższy fragment kodu JSON pokazuje, jak zwracasz błędy na poziomie urządzenia w odpowiedzi QUERY.

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

EXECUTE odpowiedź

Poniższy fragment kodu JSON pokazuje, jak zwrócić błędy na poziomie urządzenia w odpowiedzi 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
        }
      }
    ]
  }
}

Powiadomienia z błędami

Aktywne powiadomienie

Ten fragment kodu JSON pokazuje, jak zgłaszać błędy na poziomie urządzenia w powiadomieniu aktywnym.

{
  "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"
          }
        }
      }
    }
  }
}

Dalsza odpowiedź

Ten fragment kodu JSON pokazuje, jak zgłaszać błędy na poziomie urządzenia w dalszej odpowiedzi.

{
  "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"
            }
          }
        }
      }
    }
  }
}

Lista błędów

Wymienione niżej błędy powodują wygenerowanie powiązanej funkcji zamiany tekstu na mowę na urządzeniu.

Wyjątki

Wyjątek należy zwrócić wtedy, gdy z poleceniem wystąpi problem lub alert. Polecenie może się powieść lub zakończyć niepowodzeniem.

Jeśli polecenie zostało wykonane (stan = „UDAŁO SIĘ”), zgłoś wyjątki z cechą StatusReport (w przypadku urządzeń innych niż docelowe) lub przez zwrócenie odpowiedniej wartości exceptionCode (dla urządzenia docelowego).

Jeśli na przykład ekran suszarki jest pełny, użytkownik może nadal włączyć suszarkę, ale można go o tym ostrzegać. Podobnie, gdy bateria urządzenia jest słaba, a nie wyczerpana, nadal możesz wykonać polecenie, ale powiadom urządzenie, że bateria jest rozładowana.

Jeśli polecenie nie powiedzie się z powodu wyjątków, powinien pojawić się stan „EXCEPTIONS”, a wyjątki należy zgłosić za pomocą cechy StatusReport.

Wyjątek nieblokujący (SUKCES) dotyczący urządzenia docelowego

Ten przykład dotyczy zamykania drzwi:

Zamek przy drzwiach wejściowych ma słabą baterię. Zamykam zamek w drzwiach wejściowych.

{
  "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"
      }
    }]
  }
}

Nieblokujący wyjątek (SUKCES) dotyczący innego urządzenia za pomocą raportu StatusReport

Ten przykład dotyczy włączania systemu alarmowego: OK, włączam system alarmowy. Frontowe okno jest otwarte.

{
  "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"
        }]
      }
    }]
  }
}

Wyjątek blokujący inne urządzenie za pomocą raportu 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"
          }
        ]
      }
    }
  }
}

Lista wyjątków

Poniższe wyjątki powodują utworzenie powiązanej funkcji zamiany tekstu na mowę na urządzeniu.