Błędy i wyjątki

W tym dokumencie znajdziesz listę oficjalnie obsługiwanych błędów i wyjątków dotyczących urządzeń inteligentnego domu. Używaj tych kodów błędów i wyjątków w odpowiedzi na intencję lub w powiadomieniach (jeśli zostały przez Ciebie wdrożone), 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świetli użytkownikom ogólny komunikat o błędzie, np. „Przepraszamy, urządzenie jest teraz niedostępne”.

Błędy

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

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 świateł od jednego dostawcy i są one sterowane przez hub, gdy 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 nie można sterować żadnym światłem. Jeśli wszystkie urządzenia są offline, nie ma różnicy między błędami na poziomie globalnym a błędami 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 sukcesów

Błędy na poziomie globalnym

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

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

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

Przykład błędu na poziomie globalnym inSoftwareUpdate spowodowanego aktualizacją 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 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 powiadomieniu proaktywnym.

{
  "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ź uzupełniająca

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

{
  "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ą odtworzenie na urządzeniu powiązanego komunikatu 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

W przypadku problemu lub alertu związanego z poleceniem należy zwrócić wyjątek. Polecenie może się powieść lub nie.

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

Jeśli na przykład filtr kłaczków suszarki jest pełny, użytkownik nadal może włączyć suszarkę, ale warto go o tym poinformować. Podobnie, gdy urządzenie ma niski poziom naładowania baterii, ale nie jest ona pusta, nadal możesz wykonać polecenie, ale powinieneś poinformować 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 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 blokujący dotyczący innego urządzenia korzystającego z 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 odtworzona odpowiednia mowa.