Errori ed eccezioni

Questo documento elenca gli errori e le eccezioni ufficialmente supportati per i dispositivi per la casa. Utilizza questi codici di errore ed eccezioni forniti nell'intento risposta o nelle notifiche se è stato implementato, per consentire all'Assistente Google di avvisare gli utenti finali di problemi relativi a dato lo stato del comando o del dispositivo. Se la risposta contiene una formattazione errata o errorCode, l'Assistente Google invia agli utenti un messaggio di errore generico, ad esempio: "Spiacenti, device non è al momento disponibile."

Errori

Dovresti restituire un codice di errore quando un problema causa un'esecuzione o la richiesta di query non abbia esito positivo. Ad esempio, se una serratura è inceppata e non può essere bloccato o sbloccato, all'utente deve essere restituito un errore relativo a questo stato.

I codici di errore possono essere allegati a livello di dispositivo o a livello globale. Ad esempio: se un utente ha molte luci di un solo fornitore ed è controllato 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 spia è offline o errore a livello globale se l'intero hub è offline e non è possibile controllare le luci. Se tutte le i dispositivi sono offline, non c'è alcuna differenza tra l'utilizzo a livello globale o a livello di dispositivo errori. Quando un dispositivo è offline, devi segnalare lo stato {"online": false} in reportState anche se restituisci Codice di errore deviceOffline.

In sintesi:

• Errore a livello globale: tutti i dispositivi nella risposta hanno lo stesso errore
• Errore a livello locale: risposta mista con errori e casi di successo

di Gemini Advanced.

Errori a livello globale

Il seguente snippet JSON mostra come restituire errori a livello globale in 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 è: in aggiornamento:

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

Errori a livello di dispositivo

Risposta di QUERY

Il seguente snippet JSON mostra come restituisci errori a livello di dispositivo nel Risposta di QUERY.

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

ESEGUI risposta

Il seguente snippet JSON mostra come restituisci errori a livello di dispositivo nel ESEGUI la risposta.

{
  "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 errori a livello di dispositivo in un 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 errori a livello di dispositivo in un risposta aggiuntiva.

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

I seguenti errori produrranno la sintesi vocale associata sul dispositivo.

Eccezioni

Dovresti restituire un'eccezione quando esiste un problema o un avviso associato a un . Il comando potrebbe avere esito positivo o negativo.

Se il comando ha avuto esito positivo (stato = "SUCCESS"), segnala eccezioni usando la trait StatusReport (per dispositivi diversi dal target) oppure restituendo un exceptionCode appropriato (per il dispositivo di destinazione).

Ad esempio, se lo schermo della lanugine dell'asciugatrice è al completo, l'utente può comunque avviare un'asciugatrice, ma potresti voler avvisarli di questo stato. Analogamente, quando dispositivo ha la batteria scarica che non è vuota, puoi comunque eseguire un comando ma dovresti avvisarli che la batteria del dispositivo è in esaurimento.

Se il comando non riesce a causa di eccezioni, lo stato dovrebbe essere "EXCEPTIONS", e le eccezioni devono essere segnalate utilizzando il tratto StatusReport.

Eccezione non bloccante (SUCCESS) per il dispositivo di destinazione

Questo esempio riguarda la chiusura della porta:

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

{
  "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 blocco (SUCCESS) relativa a un altro dispositivo che utilizza StatusReport

Questo esempio si riferisce all'abilitazione di un sistema di sicurezza: Ok, abilita 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"
        }]
      }
    }]
  }
}

Blocco dell'eccezione per 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.