Gestire errori ed eccezioni

Quando i dispositivi o le richieste non funzionano come previsto, è importante fornire una buona gestione degli errori e una buona comunicazione per gli utenti, in modo che comprendano cosa è successo e, se possibile, come correggere il problema. Assicurati di aver pensato a possibili scenari di errore e a come deve rispondere il tuo 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 la risoluzione di questi problemi e aiutare l'utente a superarli può evitare frustrazioni e creare un'esperienza di qualità superiore per i tuoi dispositivi.

Questa guida fornisce alcuni esempi di risposte di intent che gestiscono gli errori. Consulta la sezione Errori ed eccezioni per esaminare i valori errorCode validi per errori ed eccezioni.

Esempio 1: risposta di errore per l'intent EXECUTE

Un utente finale ha installato due luci smart nel soggiorno. L'utente emette il comando "accendi le luci del soggiorno" e Google ha inviato un intent EXECUTE al tuo URL di fulfillment. Hai scoperto che i dispositivi dell'utente sono offline e non controllabili, quindi il 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 chiede all'utente "Il dispositivo non è disponibile al momento" dopo aver ricevuto la risposta. Ricorda che devi comunque inviare lo stato offline per i dispositivi nello stato del report dopo l'invio di errorCode deviceOffline nella risposta EXECUTE.

Esempio 2: eccezione non bloccante per l'intent EXECUTE

Un utente tenta di chiudere la serratura smart della porta d'ingresso utilizzando Assistant. Puoi controllare correttamente la serratura, ma la batteria del dispositivo è in esaurimento, quindi l'evasione restituisce una risposta EXECUTE con status SUCCESS e exceptionCode lowBattery.

Questo esempio mostra come inviare una risposta EXECUTE con un exceptionCode da un dispositivo di chiusura 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 chiede all'utente "la batteria del dispositivo è in esaurimento" dopo aver ricevuto la risposta.

Esempio 3: notifiche proattive degli errori

In alcuni casi, può essere utile avvisare gli utenti di un errore, in particolare per le funzioni che gli utenti si aspettano di completare automaticamente. Per le caratteristiche che supportano le notifiche proattive, puoi notificare in modo proattivo all'utente quando si verifica un errore se hai implementato le smart home notifiche proattive.

Una smart dryer è in funzione e qualcuno apre lo sportello prima che il ciclo termini. Puoi chiamare il metodo reportStateAndNotifications dell'API Google Home Graph 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
        }
      }
    }
  }
}

Il Assistant chiede all'utente "la porta del dispositivo è aperta" dopo aver ricevuto la notifica. Puoi inviare gli stati dei dispositivi corrispondenti insieme alle notifiche nello stesso payload.

Esempio 4: notifica di follow-up

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

Un utente invia un comando per chiudere la porta del garage, ma la porta si blocca 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 chiede all'utente "il dispositivo è bloccato" dopo aver ricevuto la notifica. Puoi inviare gli stati dei dispositivi corrispondenti con le notifiche nello stesso payload.

Per ulteriori informazioni e errorCodes dettagliati, consulta la documentazione di riferimento Errori ed eccezioni.