Erreurs et exceptions

Ce document répertorie les erreurs et les exceptions officiellement acceptées pour les appareils connectés. Veuillez utiliser les erreurs et les codes d'exception indiqués dans l'intent. ou dans les notifications si vous l'avez implémenté, de sorte que l'Assistant Google alerte les utilisateurs finaux en cas de problème une commande ou un état d'appareil donnés. Si la réponse présente une mise en forme incorrecte ou errorCode, l'Assistant Google renvoie aux utilisateurs un message d'erreur générique, par exemple : "Désolé, l'appareil n'est pas disponible pour le moment."

Erreurs

Vous devez renvoyer un code d'erreur lorsqu'un problème entraîne une exécution ou l'échec de la requête. Par exemple, si une serrure est bloquée et ne peut pas verrouillé ou déverrouillé, une erreur concernant cet état doit être renvoyée à l'utilisateur.

Les codes d'erreur peuvent être ajoutés au niveau de l'appareil ou au niveau global. Par exemple : si un utilisateur a plusieurs ampoules d'un fournisseur et qu'elles sont contrôlées par un hub, lorsque l'utilisateur demande à éteindre toutes les lumières, le fournisseur peut renvoyer erreur au niveau de l'appareil si une seule lumière est hors connexion, ou erreur globale si son hub est hors connexion et aucune lumière ne peut être contrôlée. Si toutes les ne sont pas connectés à Internet, il n'existe aucune différence entre l'utilisation au niveau global ou au niveau de l'appareil les erreurs. Lorsqu'un appareil est hors connexion, vous devez signaler l'état {"online": false} dans reportState, même si vous renvoyez le Code d'erreur deviceOffline.

En résumé :

• Erreur globale: tous les appareils figurant dans la réponse présentent la même erreur.
• Erreur locale: réponse mixte avec des cas d'erreur et de réussite

Erreurs au niveau global

L'extrait de code JSON suivant montre comment renvoyer des erreurs au niveau global dans les QUERY ou EXECUTE.

Voici un exemple d'erreur globale deviceOffline liée au hub : hors connexion:

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

Voici un exemple d'erreur globale inSoftwareUpdate liée au hub : mise à jour:

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

Erreurs au niveau de l'appareil

Réponse QUERY

L'extrait de code JSON suivant montre comment renvoyer des erreurs au niveau de l'appareil dans le QUERY.

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

Réponse EXECUTE

L'extrait de code JSON suivant montre comment renvoyer des erreurs au niveau de l'appareil dans le EXECUTE.

{
  "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
        }
      }
    ]
  }
}

Notifications avec erreurs

Notification proactive

L'extrait de code JSON suivant montre comment signaler les erreurs au niveau de l'appareil dans un notification proactive.

{
  "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"
          }
        }
      }
    }
  }
}

Réponse de suivi

L'extrait de code JSON suivant montre comment signaler les erreurs au niveau de l'appareil dans un une réponse de suivi.

{
  "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"
            }
          }
        }
      }
    }
  }
}

Liste d'erreurs

Les erreurs suivantes génèrent la synthèse vocale associée sur l'appareil.

Exceptions

Vous devez renvoyer une exception lorsqu'un problème ou une alerte est associé à un . La commande peut réussir ou échouer.

Si la commande a abouti (état = "SUCCÈS"), signalez les exceptions. à l'aide de la caractéristique StatusReport (pour les appareils autres que la cible) ; ou en renvoyant un exceptionCode approprié (pour l'appareil cible).

Par exemple, si l'écran du sèche-linge est plein, l'utilisateur peut quand même démarrer son sèche-linge, mais vous pouvez l’avertir de cet état. De même, lorsqu'un appareil a une batterie faible qui n'est pas vide, vous pouvez quand même exécuter une commande mais vous devez l'informer que la batterie de l'appareil est faible.

Si la commande échoue en raison d'exceptions, l'état doit être "EXCEPTIONS". Les exceptions doivent être signalées à l'aide de la caractéristique StatusReport.

Exception non bloquante (SUCCÈS) concernant l'appareil cible.

Cet exemple sert à verrouiller la porte:

Les piles de la serrure de la porte d'entrée sont faibles. Je verrouille la porte d'entrée.

{
  "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"
      }
    }]
  }
}

Exception non bloquante (SUCCÈS) concernant un autre appareil utilisant StatusReport

Cet exemple concerne l'activation d'un système de sécurité: D'accord, j'active le système de sécurité. La fenêtre avant est ouverte.

{
  "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"
        }]
      }
    }]
  }
}

Blocage de l'exception concernant un autre appareil à l'aide du rapport d'état

{
  "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"
          }
        ]
      }
    }
  }
}

Liste d'exceptions

Les exceptions suivantes généreront la synthèse vocale associée sur l'appareil.