Gestire errori ed eccezioni

Se i dispositivi o le richieste non funzionano come previsto, è importante fornire informazioni una buona gestione degli errori e una buona comunicazione per gli utenti, in modo che capiscano cosa e, ove possibile, come correggerlo. Assicurati di riflettere attentamente possibili scenari di errore e come risponderà il dispositivo: cosa succede se un utente interrompe un'attività in corso? Cosa succede se un utente richiede un'azione da un dispositivo mentre è offline? Pianificare questi problemi e aiutare l'utente a riprendersi possono evitare la frustrazione degli utenti e creare un'esperienza di qualità superiore per i tuoi dispositivi.

Questa guida fornisce alcuni esempi di risposte agli intent che gestiscono gli errori. Consulta in Errori ed eccezioni per esamina i valori errorCode validi per individuare errori ed eccezioni.

Esempio 1: risposta di errore per l'intent EXECUTE

Un utente finale ha due luci smart installate in salotto. L'utente emette un comando "accendi le luci del salotto" e Google ha inviato un EXECUTE all'URL di completamento. Hai rilevato che i dispositivi dell'utente sono offline e non controllabile, quindi il tuo fulfillment restituisce una risposta EXECUTE con status ERROR e errorCode deviceOffline.

Questo esempio mostra come restituire una risposta EXECUTE con un errorCode da un dispositivo leggero come descritto in precedenza:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "light-device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "light-device-id-2"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

Google Assistant chiederà all'utente "il dispositivo è non disponibile al momento" dopo aver ricevuto la risposta. Ricorda che devi ancora richiesta di invio dello stato offline per i dispositivi in stato del report dopo l'invio errorCode deviceOffline nella risposta EXECUTE.

Esempio 2: eccezione non di blocco per l'intent EXECUTE

Una utente prova a chiudere la serratura smart davanti alla porta principale usando un dispositivo con Assistant. Puoi controllare correttamente la serratura, noti che la batteria del dispositivo è in esaurimento, pertanto l'evasione degli ordini restituisce un EXECUTE risposta con status SUCCESS e exceptionCode lowBattery.

Questo esempio mostra come inviare una risposta EXECUTE con un exceptionCode da un dispositivo di blocco come descritto in precedenza:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["lock-device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

Assistant chiederà all'utente "il dispositivo è in esaurimento batteria" dopo aver ricevuto la risposta.

Esempio 3: notifiche proattive di errori

In alcuni casi, può essere utile avvisare gli utenti di un errore, in particolare per funzioni che gli utenti si aspettano di completare automaticamente. Per i tratti che supportare le notifiche proattive, puoi informare in modo proattivo l'utente mentre si verifica un errore se hai implementato smart home notifiche proattive.

Un'asciugatrice smart è in funzione e qualcuno apre la porta prima del termine del ciclo. Puoi chiamare l'API Google Home Graph metodo reportStateAndNotifications per inviare una notifica proattiva con un errorCode:

Questo esempio mostra come inviare una notifica proattiva con un errorCode da un'asciugatrice come descritto in precedenza:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "dryer-device-id": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      },
      "states": {
        "dryer-device-id": {
          "isRunning": false,
          "isPaused": true
        }
      }
    }
  }
}

Assistant chiederà all'utente "la porta del dispositivo è aperto" dopo aver ricevuto la notifica. Puoi inviare il codice corrispondente gli stati dei dispositivi insieme alle notifiche nello stesso payload.

Esempio 4: notifica di follow-up

Per i comandi traits che supportano le notifiche di follow-up, puoi inviare un una notifica di follow-up all'utente mentre si verifica un errore o un'eccezione, se hai implementato smart home notifiche di follow-up.

Una utente invia un comando per chiudere la porta del garage, che però è inceppata durante la chiusura. Puoi inviare una notifica di follow-up con un errorCode:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "door-device-id": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "follow-up-token-1"
            }
          }
        }
      },
      "states": {
        "door-device-id": {
          "openPercent": 70
        }
      }
    }
  }
}

Assistant chiederà all'utente "il dispositivo è bloccato" dopo aver ricevuto la notifica. Puoi inviare il codice corrispondente gli stati dei dispositivi con notifiche nello stesso payload.

Per ulteriori informazioni e per i dettagli relativi a errorCodes, consulta Errori ed eccezioni documentazione di riferimento.