Gérer les erreurs et les exceptions

Lorsque les appareils ou les requêtes ne fonctionnent pas comme prévu, il est important d'offrir à vos utilisateurs une bonne gestion des erreurs et une bonne communication afin qu'ils comprennent ce qu'il s'est passé et, dans la mesure du possible, comment le résoudre. Réfléchissez aux scénarios de défaillance possibles et à la manière dont votre appareil réagit: 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 hors connexion à un appareil ? En planifiant ces problèmes et en aidant vos utilisateurs à les résoudre, vous pouvez leur éviter la frustration et améliorer l'expérience de vos appareils.

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

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

Un utilisateur final possède deux ampoules connectées et les installe dans le salon. L'utilisateur exécute une commande "allume les lumières du salon", et Google a envoyé un intent EXECUTE à votre URL de traitement. Vous avez constaté que les appareils de l'utilisateur sont hors connexion et non contrôlables. Par conséquent, votre traitement 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"
      }
    ]
  }
}

Une fois la réponse reçue, Google Assistant indique à l'utilisateur que l'appareil n'est pas disponible actuellement. N'oubliez pas que vous devez toujours envoyer l'état hors connexion des appareils à l'état de rapport après avoir envoyé errorCode deviceOffline dans la réponse EXECUTE.

Exemple 2: Exception non bloquante pour l'intent EXECUTE

Un utilisateur tente de verrouiller la serrure connectée à la porte d'entrée avec un appareil avec Assistant. Vous pouvez contrôler le verrouillage, mais vous constatez que la batterie de l'appareil est faible. Votre traitement renvoie donc une réponse EXECUTE avec status SUCCESS et exceptionCode lowBattery.

Cet exemple montre comment envoyer une réponse EXECUTE avec une exceptionCode à partir d'un appareil de verrouillage, 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 demandera à l'utilisateur "l'appareil a une batterie faible" 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 en cas d'erreur, en particulier pour les fonctions que les utilisateurs s'attendent à terminer automatiquement. Pour les caractéristiques qui acceptent les notifications proactives, vous pouvez avertir l'utilisateur de manière proactive en cas d'erreur si vous avez implémenté les notifications proactives smart home.

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

Cet exemple montre comment envoyer une notification proactive avec un 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 recevra une notification indiquant que la porte de l'appareil est ouverte. Vous pouvez envoyer les états d'appareil correspondants avec les notifications dans la même charge utile.

Exemple 4: Notification de suivi

Pour les commandes de caractéristiques qui prennent en charge les notifications de suivi, vous pouvez envoyer une notification de suivi à l'utilisateur lorsqu'une erreur ou une exception se produit, si vous avez implémenté les notifications de suivi smart home.

Un utilisateur lance une commande pour fermer la porte du garage, mais la porte est bloquée lors de la fermeture. 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
        }
      }
    }
  }
}

Le Assistant demande à l'utilisateur "l'appareil est bloqué" après avoir reçu la notification. Vous pouvez envoyer les états d'appareil correspondants avec des notifications dans la même charge utile.

Pour en savoir plus et obtenir des informations détaillées sur errorCodes, consultez la documentation de référence sur les erreurs et exceptions.