Błędy i wyjątki

W tym dokumencie znajdziesz listę oficjalnie obsługiwanych błędów i wyjątków dotyczących inteligentnych urządzeń domowych. Użyj tych kodów błędów i wyjątków w odpowiedzi na intencję lub w powiadomieniach, jeśli masz je wdrożone, aby Asystent Google powiadamiał użytkowników o problemach związanych z danym poleceniem lub stanem urządzenia. Jeśli odpowiedź zawiera nieprawidłowe formatowanie lub errorCode, Asystent Google wyświetla użytkownikom ogólny komunikat o błędzie, na przykład „Urządzenie jest teraz niedostępne”.

Błędy

Jeśli problem spowoduje niepowodzenie żądania wykonania lub zapytania, zwróć kod błędu. Jeśli na przykład zamek drzwi jest zablokowany i nie można go zamknąć ani otworzyć, użytkownik powinien otrzymać błąd 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 lamp od jednego dostawcy, które są sterowane przez koncentrator, i poprosi o wyłączenie wszystkich lamp, dostawca może zwrócić błąd na poziomie urządzenia, jeśli jedna lampa jest offline, lub błąd na poziomie globalnym, jeśli cały koncentrator jest offline i nie można sterować żadnymi lampami. 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.

Podsumowanie:

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

Błędy na poziomie globalnym

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

Przykładem błędu na poziomie globalnym deviceOffline spowodowanego tym, że centrum jest offline, jest:

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

Przykład błędu na poziomie globalnym inSoftwareUpdate spowodowanego aktualizacją centrum:

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

Błędy na poziomie urządzenia

Odpowiedź na ZAPYTANIE

Poniższy fragment kodu JSON pokazuje, jak zwracać 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"
      }
    }
  }
}

Odpowiedź EXECUTE

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

Poniższy fragment kodu JSON pokazuje, jak zgłaszać 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"
          }
        }
      }
    }
  }
}

Odpowiedź na dalsze pytania

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

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

W przypadku tych błędów na urządzeniu zostanie odtworzony powiązany komunikat TTS.

Raportowanie stanu online i offline

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

Wyjątki

Jeśli wystąpi problem lub alert związany z poleceniem, należy zwrócić wyjątek. Polecenie może zakończyć się powodzeniem lub niepowodzeniem.

Jeśli polecenie zostało wykonane (stan = „SUCCESS”), zgłoś wyjątki za pomocą cechy StatusReport (w przypadku urządzeń innych niż docelowe) lub zwracając odpowiedni błąd exceptionCode (w przypadku urządzenia docelowego).

Jeśli na przykład filtr kłaczków w suszarce jest pełny, użytkownik nadal może uruchomić suszarkę, ale warto go ostrzec o tym stanie. Podobnie, gdy urządzenie ma słabą baterię, która nie jest rozładowana, nadal możesz wykonać polecenie, ale poinformuj użytkownika, że bateria urządzenia jest słaba.

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

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

Ten przykład dotyczy blokowania drzwi:

Bateria zamka drzwi frontowych jest słaba. 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"
      }
    }]
  }
}

Wyjątek nieblokujący (SUCCESS) dotyczący innego urządzenia korzystającego ze StatusReport

Ten przykład dotyczy włączania systemu alarmowego: OK, włączam system alarmowy. Przednie 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"
        }]
      }
    }]
  }
}

Blokowanie wyjątku dotyczącego innego urządzenia za pomocą funkcji 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

W przypadku tych wyjątków na urządzeniu zostanie wygenerowany powiązany komunikat TTS.