Błędy i wyjątki

Ten dokument zawiera oficjalne obsługiwane błędy i wyjątki dotyczące inteligentnych urządzeń domowych. Używaj tych kodów błędów i wyjątków w odpowiedzi na zamiar lub w powiadomieniach, jeśli zostały przez Ciebie zaimplementowane, aby Asystent Google informował 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, np. „Urządzenie jest teraz niedostępne”.

Błędy

Zwróć kod błędu, jeśli problem powoduje wykonanie polecenia lub zapytania. Jeśli na przykład zamek w drzwiach się zaciął i nie można go zamknąć ani odblokować, powinien zostać zwrócony użytkownikowi komunikat o tym stanie.

Kody błędów można dołączać na poziomie urządzenia lub globalnego. Jeśli na przykład użytkownik ma wiele świateł od jednego dostawcy i jest sterowany przez centrum, to gdy użytkownik prosi 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ć żadnymi źródłami światła. Jeśli wszystkie urządzenia są offline, nie ma różnicy między błędami na poziomie globalnym lub urządzenia. Gdy urządzenie jest offline, należy zgłosić stan {"online": false} w reportState, nawet jeśli kod błędu deviceOffline jest zwracany.

Podsumowanie:

• Błąd na poziomie globalnym: ten sam błąd występuje na wszystkich urządzeniach w odpowiedzi
• Błąd na poziomie lokalnym: odpowiedź mieszana z błędami i przypadkami sukcesu

Błędy na poziomie globalnym

Fragment kodu JSON pokazuje, jak zwracasz błędy na poziomie globalnym w odpowiedzi na zapytanie QUERY lub EXECUTE.

Przykład błędu na poziomie globalnym deviceOffline w centrum z powodu centrum jest offline:

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

Aktualizujemy na przykład błąd globalny na poziomie inSoftwareUpdate z powodu działania centrum:

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

Błędy na poziomie urządzenia

Odpowiedź QUERY

Fragment kodu JSON pokazuje, jak zwracasz błędy na poziomie urządzenia w odpowiedzi na zapytanie QUERY.

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

WYKONAJ Odpowiedź

Ten 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

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

Dalsza odpowiedź

Ten fragment kodu JSON pokazuje, jak zgłosić błędy na poziomie urządzenia w kolejnej 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

Poniższe błędy powodują wygenerowanie powiązanego tekstu na urządzeniu.

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

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

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