Errori ed eccezioni

Questo documento elenca gli errori e le eccezioni supportati ufficialmente per i dispositivi per la smart home. Utilizza questi codici di errore ed eccezione nella risposta all'intent o nelle notifiche, se le hai implementate, in modo che l'Assistente Google avvisi gli utenti finali di problemi relativi a un determinato comando o stato del dispositivo. Se la risposta contiene una formattazione errata o errorCode, l'Assistente Google fornisce agli utenti un messaggio di errore generico, ad esempio "Spiacenti, dispositivo non è disponibile al momento".

Errori

Devi restituire un codice di errore quando un problema causa l'esito negativo di una richiesta di esecuzione o di query. Ad esempio, se una serratura è inceppata e non può essere bloccata o sbloccata, all'utente deve essere restituito un errore relativo a questo stato.

I codici di errore possono essere associati a livello di dispositivo o a livello globale. Ad esempio, se un utente ha molte luci di un provider e queste sono controllate da un hub, quando l'utente chiede di spegnere tutte le luci, il provider potrebbe restituire un errore a livello di dispositivo se una singola luce è offline o un errore a livello globale se l'intero hub è offline e non è possibile controllare nessuna luce. Se tutti i dispositivi sono offline, non c'è differenza tra l'utilizzo di errori a livello globale o a livello di dispositivo.

In sintesi:

• Errore a livello globale: tutti i dispositivi nella risposta presentano lo stesso errore
• Errore a livello locale: risposta mista con casi di errore e di esito positivo

Errori a livello globale

Il seguente snippet JSON mostra come restituire errori a livello globale nella risposta QUERY o EXECUTE.

Un esempio di errore a livello globale deviceOffline dovuto all'hub offline è:

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

Un esempio di errore a livello globale inSoftwareUpdate dovuto all'aggiornamento dell'hub è:

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

Errori a livello di dispositivo

Risposta QUERY

Il seguente snippet JSON mostra come restituire gli errori a livello di dispositivo nella risposta QUERY.

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

Risposta EXECUTE

Lo snippet JSON seguente mostra come restituire gli errori a livello di dispositivo nella risposta 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
        }
      }
    ]
  }
}

Notifiche con errori

Notifica proattiva

Il seguente snippet JSON mostra come segnalare gli errori a livello di dispositivo in una notifica proattiva.

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

Risposta aggiuntiva

Il seguente snippet JSON mostra come segnalare gli errori a livello di dispositivo in una risposta di follow-up.

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

Elenco errori

I seguenti errori genereranno il TTS associato sul dispositivo.

Segnalazioni sullo stato online e offline

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

Eccezioni

Devi restituire un'eccezione quando si verifica un problema o un avviso associato a un comando. Il comando potrebbe riuscire o non riuscire.

Se il comando è andato a buon fine (stato = "SUCCESS"), segnala le eccezioni utilizzando il tratto StatusReport (per i dispositivi diversi da quello di destinazione) o restituendo un exceptionCode appropriato (per il dispositivo di destinazione).

Ad esempio, se il filtro per lanugine dell'asciugatrice è pieno, l'utente può comunque avviare l'asciugatrice, ma potresti volerlo avvisare di questo stato. Analogamente, quando un dispositivo ha la batteria in esaurimento, ma non scarica, puoi comunque eseguire un comando, ma devi informare l'utente che la batteria del dispositivo è in esaurimento.

Se il comando non va a buon fine a causa di eccezioni, lo stato deve essere "EXCEPTIONS" e le eccezioni devono essere segnalate utilizzando il tratto StatusReport.

Eccezione non bloccante (SUCCESS) relativa al dispositivo di destinazione

Questo esempio riguarda la chiusura della porta:

La batteria della serratura della porta d'ingresso è in esaurimento. Chiudo la serratura della porta principale.

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

Eccezione non di blocco (SUCCESS) relativa a un altro dispositivo che utilizza StatusReport

Questo esempio riguarda l'abilitazione di un sistema di sicurezza: Ok, abilito il sistema di sicurezza. La finestra anteriore è aperta.

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

Eccezione di blocco relativa a un altro dispositivo che utilizza 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"
          }
        ]
      }
    }
  }
}

Elenco di eccezioni

Le seguenti eccezioni genereranno il TTS associato sul dispositivo.