Errori ed eccezioni

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

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 è bloccata e non può essere chiusa o aperta, all'utente deve essere restituito un errore relativo a questo stato.

I codici di errore possono essere allegati a livello di dispositivo o globale. Ad esempio, se un utente ha molte luci di un fornitore e sono controllate da un hub, quando l'utente chiede di spegnere tutte le luci, il fornitore 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 le luci. Se tutti i dispositivi sono offline, non c'è alcuna 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 successo

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'hub è l'aggiornamento:

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

Il seguente snippet JSON mostra come restituire 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 di follow-up

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 la sintesi vocale associata sul dispositivo.

Report 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 avere esito positivo o negativo.

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

Ad esempio, se il filtro della lanugine dell'asciugatrice è pieno, l'utente può comunque avviare l'asciugatrice, ma potresti volerlo avvisare di questo stato. Allo stesso modo, quando un dispositivo ha una batteria in esaurimento, ma non completamente scarica, puoi comunque eseguire un comando, ma devi comunicare all'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" (ECCEZIONI) 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 principale è in esaurimento. Chiudo a chiave la 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 bloccante (SUCCESS) relativa a un altro dispositivo che utilizza StatusReport

Questo esempio riguarda l'attivazione di un sistema di sicurezza: Ok, abilito il sistema di sicurezza. Il finestrino anteriore è aperto.

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

Le seguenti eccezioni produrranno la sintesi vocale associata sul dispositivo.