Błędy i wyjątki

Ten dokument zawiera listę oficjalnie obsługiwanych błędów i wyjątków dotyczących urządzeń smart home. Używaj tych kodów błędów i wyjątków w odpowiedzi na intencję lub w powiadomieniach, jeśli je wdrożysz, aby Asystent Google ostrzegał 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 „Przepraszamy, ale urządzenie jest teraz niedostępne”.

Błędy

Kod błędu należy zwrócić, gdy problem powoduje niepowodzenie wykonania lub żądania zapytania. Jeśli na przykład zamek drzwi jest zablokowany i nie można go zamknąć ani odblokować, użytkownik powinien otrzymać komunikat o tym stanie.

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 urządzeń od jednego dostawcy i są one kontrolowane przez hub, gdy użytkownik poprosi o wyłączenie wszystkich świateł, dostawca może zwrócić błąd na poziomie urządzenia, jeśli jedno światło jest offline, lub błąd na poziomie globalnym, jeśli cały hub jest offline i żadne światła nie mogą być kontrolowane. Jeśli wszystkie urządzenia są offline, nie ma różnicy między błędami na poziomie globalnym a na poziomie urządzenia.

Gdy urządzenie jest offline, w ciągu 5 minut od momentu wystąpienia problemu z urządzeniem należy przekazać {"online": false} do Raportu o stanie.

W skrócie:

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

Błędy na poziomie globalnym

Ten fragment kodu JSON pokazuje, jak zwracać błędy na poziomie globalnym w odpowiedziach QUERY lub EXECUTE.

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

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

Przykład błędu na poziomie globalnym inSoftwareUpdate spowodowanego przez aktualizowanie huba:

{
  "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 na zapytanie.

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

Aktywna ochrona

Ten fragment kodu JSON pokazuje, jak zgłaszać błędy na poziomie urządzenia w ramach proaktywnej funkcji powiadomień.

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

Ten fragment kodu JSON pokazuje, jak zgłaszać błędy na poziomie urządzenia w dodatkowej 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 spowodują wyświetlenie na urządzeniu powiązanego z nimi tekstu syntetycznego.

Wyjątki

Wyjątek powinien zostać zwrócony, gdy występuje problem lub alert związany z poleceniem. Polecenie może się udać lub nie.

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

Jeśli na przykład koszyk pralki jest pełny, użytkownik może nadal włączyć pralkę, ale warto go o tym ostrzec. Podobnie, gdy urządzenie ma słabą baterię, ale nie jest ona jeszcze pusta, możesz nadal wykonać polecenie, ale musisz poinformować użytkownika o tym, że bateria jest słaba.

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

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

Ten przykład dotyczy zamykania drzwi:

Zamek w 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"
      }
    }]
  }
}

Wyjątek nieblokujący (SUCCESS) dotyczący innego urządzenia korzystającego z 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"
        }]
      }
    }]
  }
}

Wyjątek blokowania dotyczące innego urządzenia 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

Na tych urządzeniach będą generowane powiązane usługi TTS: