Gérer les erreurs et les exceptions

Lorsque des appareils ou des requêtes ne fonctionnent pas comme prévu, il est important de fournir une bonne gestion des erreurs et une bonne communication pour vos utilisateurs afin qu’ils comprennent et, dans la mesure du possible, comment le corriger. Assurez-vous de réfléchir à les scénarios de défaillance possibles et la réaction de l'appareil. Que se passe-t-il si un utilisateur interrompt une tâche en cours ? Que se passe-t-il si un utilisateur demande une action à partir d'un appareil ? lorsqu'il est hors connexion ? Planifier ces problèmes et aider les utilisateurs à s'en remettre peuvent éviter la frustration des utilisateurs et créer une expérience de meilleure qualité pour vos appareils.

Ce guide fournit quelques exemples de réponses d'intent qui gèrent les erreurs. Voir la section Erreurs et exceptions pour Vérifiez les valeurs errorCode valides pour identifier les erreurs et les exceptions.

Exemple 1: Réponse d'erreur pour l'intent EXECUTE

Un utilisateur final a installé deux ampoules connectées dans son salon. L'utilisateur émet une commande "allume les lumières du salon" et Google a envoyé un EXECUTE vers votre URL de traitement. Vous avez constaté que les appareils de l'utilisateur sont hors connexion et non contrôlable. Par conséquent, votre fulfillment renvoie une réponse EXECUTE avec status ERROR et errorCode deviceOffline.

Cet exemple montre comment renvoyer une réponse EXECUTE avec une errorCode à partir d'un appareil léger, comme décrit précédemment:

{
  "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 affichera une invite indiquant que les appareils sont actuellement indisponible." après avoir reçu la réponse. N'oubliez pas que vous doivent envoyer l'état hors connexion pour les appareils en état de signalement après l'envoi errorCode deviceOffline dans la réponse EXECUTE.

Exemple 2: Exception non bloquante pour l'intent EXECUTE

Un utilisateur essaie de verrouiller sa serrure connectée à la porte d'entrée en utilisant un appareil avec Assistant Vous pouvez contrôler avec succès sa serrure, mais vous constatez que la batterie de l'appareil est faible, donc votre traitement renvoie un EXECUTE réponse avec status SUCCESS et exceptionCode lowBattery.

Cet exemple montre comment envoyer une réponse EXECUTE avec une exceptionCode sur un appareil verrouillé, comme décrit précédemment:

{
  "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 affichera une invite indiquant que l'appareil a une faible de batterie" après avoir reçu la réponse.

Exemple 3: Notifications d'erreur proactives

Dans certains cas, il peut être utile d'alerter les utilisateurs d'une erreur, en particulier pour que les utilisateurs s'attendent à exécuter automatiquement. Pour les caractéristiques qui notifications proactives, vous pouvez avertir l'utilisateur de manière proactive pendant qu'un une erreur se produit si vous avez implémenté smart home notifications proactives.

Un sèche-linge connecté est en cours, et quelqu'un ouvre la porte avant la fin du cycle. Vous pouvez appeler l'API Google Home Graph reportStateAndNotifications pour envoyer une notification proactive avec une errorCode:

Cet exemple montre comment envoyer une notification proactive avec une errorCode à partir d'un sèche-linge, comme décrit précédemment:

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 enverra une invite indiquant que la porte de l'appareil est ouvert" après avoir reçu la notification. Vous pouvez envoyer les réponses états de l'appareil avec les notifications dans la même charge utile.

Exemple 4: Notification de suivi

Pour les commandes de traits compatibles avec les notifications de suivi, vous pouvez envoyer une notification de suivi à l'utilisateur lors d'une erreur ou d'une exception, vous avez implémenté smart home notifications de suivi.

Un utilisateur ordonne à l'utilisateur de fermer sa porte de garage, mais celle-ci est bloquée lors de la clôture. Vous pouvez envoyer une notification de suivi avec 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 affichera une invite indiquant que l'appareil est bloquée" après avoir reçu la notification. Vous pouvez envoyer les réponses états des appareils avec des notifications dans la même charge utile.

Pour obtenir plus d'informations et des informations détaillées sur errorCodes, consultez les Erreurs et exceptions documentation de référence.