Błędy i wyjątki

Ten dokument zawiera listę oficjalnie obsługiwanych błędów i wyjątków dotyczących inteligentnych urządzeń domowych. Podaj te kody błędów i wyjątków w odpowiedzi na intencję lub w powiadomieniach, jeśli zostały zaimplementowane, aby Asystent Google ostrzegał użytkowników o problemach związanych z danym poleceniem lub stanem urządzenia. Jeśli odpowiedź ma nieprawidłowy format lub errorCode, Asystent Google wyświetli ogólny komunikat o błędzie, np. „Urządzenie jest w tej chwili niedostępne”.

Błędy

Zwracaj kod błędu, gdy problem powoduje niepowodzenie wykonania lub żądania zapytania. Jeśli na przykład zamki w drzwiach się zacięły i nie można ich zablokować ani odblokować, użytkownik powinien wyświetlić komunikat o błędzie o tym stanie.

Kody błędów można dołączyć na poziomie urządzenia lub globalnego. Jeśli na przykład użytkownik ma wiele źródeł światła od jednego dostawcy, które są sterowane przez centrum, to gdy użytkownik poprosi o wyłączenie wszystkich świateł, dostawca może zwrócić błąd na poziomie urządzenia, jeśli pojedynczy punkt oświetlenia jest offline, lub błąd na poziomie globalnym, gdy całe centrum jest offline i nie da się sterować żadnymi oświetleniem. Jeśli wszystkie urządzenia działają w trybie offline, nie ma różnicy między wystąpieniem błędów na poziomie globalnym czy na poziomie urządzenia. Gdy urządzenie jest offline, stan {"online": false} w parametrze reportState musisz zgłaszać nawet wtedy, gdy zwracasz 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 globalne w odpowiedzi QUERY lub EXECUTE.

Przykład błędu globalnego deviceOffline, który pojawia się w centrum, jest w trybie offline:

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

Przykładowy błąd globalny inSoftwareUpdate spowodowany przez centrum jest aktualizowany:

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

Błędy na poziomie urządzenia

Odpowiedź na zapytanie QUERY

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

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

WYKONAJ odpowiedź

Poniższy fragment kodu JSON pokazuje, jak zwracasz 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łosić błędy na poziomie urządzenia w aktywnym powiadomieniu.

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

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

{
  "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 spowodują zamianę tekstu na mowę na urządzeniu.

działania związane z wyjątkami.

W przypadku wystąpienia problemu lub alertu powiązanego z poleceniem należy zwrócić wyjątek. Polecenie może się udać lub zakończyć niepowodzeniem.

Jeśli polecenie zadziałało (stan = „SUCCESS”), zgłoś wyjątki za pomocą cechy 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 warto mu o tym ostrzec. Podobnie gdy urządzenie ma słabą baterię, która nie jest rozładowana, nadal możesz wykonać polecenie, ale poinformować użytkownika o niskim poziomie naładowania baterii.

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

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

Ten przykład dotyczy zamknięcia drzwi:

Zamek przy drzwiach frontowych ma słabą baterię. Zamykam drzwi wejściowe.

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

Wyjątek nieblokujący (SUCCESS) dotyczący innego urządzenia przy użyciu 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 przy użyciu 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

Wymienione poniżej wyjątki powodują przekształcenie tekstu na mowę na urządzeniu.