Errores y excepciones

En este documento, se enumeran los errores y las excepciones compatibles oficialmente con los dispositivos para la casa inteligente. Usa estos códigos de error y excepción en la respuesta de la intención o en las notificaciones, si las implementaste, para que Asistente de Google alerte a los usuarios finales sobre los problemas relacionados con un comando o estado del dispositivo determinados. Si la respuesta contiene un formato incorrecto o errorCode, Asistente de Google les muestra a los usuarios un mensaje de error genérico, por ejemplo, "Lo siento, dispositivo no está disponible en este momento".

Errores

Debes devolver un código de error cuando un problema provoque que falle una solicitud de ejecución o consulta. Por ejemplo, si una cerradura está trabada y no se puede abrir ni cerrar, se debe mostrar un error sobre este estado al usuario.

Los códigos de error se pueden adjuntar a nivel del dispositivo o a nivel global. Por ejemplo, si un usuario tiene muchas luces de un proveedor y se controlan con un concentrador, cuando el usuario pide que se apaguen todas las luces, el proveedor puede devolver un error a nivel del dispositivo si una sola luz está sin conexión o un error a nivel global si todo el concentrador está sin conexión y no se pueden controlar las luces. Si todos los dispositivos están sin conexión, no hay diferencia entre usar errores a nivel global o a nivel del dispositivo.

Resumen:

• Error a nivel global: Todos los dispositivos en la respuesta tienen el mismo error
• Error a nivel local: Respuesta mixta con casos de error y éxito

Errores a nivel global

En el siguiente fragmento de JSON, se muestra cómo devolver errores a nivel global en la respuesta de QUERY o EXECUTE.

A continuación, se muestra un ejemplo del error deviceOffline a nivel global debido a que la central está sin conexión:

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

A continuación, se muestra un ejemplo del error inSoftwareUpdate a nivel global debido a la actualización del centro:

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

Errores a nivel del dispositivo

Respuesta de QUERY

En el siguiente fragmento de JSON, se muestra cómo devolver errores a nivel del dispositivo en la respuesta de QUERY.

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

Respuesta de EXECUTE

En el siguiente fragmento de código JSON, se muestra cómo devolver errores a nivel del dispositivo en la respuesta de 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
        }
      }
    ]
  }
}

Notificaciones con errores

Notificación proactiva

En el siguiente fragmento de código JSON, se muestra cómo informar errores a nivel del dispositivo en una notificación proactiva.

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

Respuesta de seguimiento

En el siguiente fragmento de JSON, se muestra cómo informar errores a nivel del dispositivo en una respuesta de seguimiento.

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

Lista de errores

Los siguientes errores producirán la TTS asociada en el dispositivo.

Informes de estado en línea y sin conexión

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

Excepciones

Debes devolver una excepción cuando haya un problema o una alerta asociados a un comando. El comando podría tener éxito o fallar.

Si el comando se ejecutó correctamente (status = "SUCCESS"), informa las excepciones con el rasgo StatusReport (para dispositivos que no sean el objetivo) o devolviendo un exceptionCode adecuado (para el dispositivo objetivo).

Por ejemplo, si el filtro de pelusa de la secadora está lleno, el usuario puede iniciar la secadora, pero es posible que desees advertirle sobre este estado. Del mismo modo, cuando un dispositivo tiene batería baja, pero no está agotada, puedes ejecutar un comando, pero debes informarle al usuario que la batería del dispositivo está baja.

Si el comando falla debido a excepciones, el estado debe ser "EXCEPTIONS", y las excepciones se deben informar con el rasgo StatusReport.

Excepción no bloqueante (SUCCESS) sobre el dispositivo de destino

Este ejemplo es para trabar la puerta:

La batería de la cerradura de la puerta principal está baja. Trabando la puerta principal.

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

Excepción que no genera bloqueo (SUCCESS) sobre otro dispositivo que usa StatusReport

Este ejemplo es para activar un sistema de seguridad: De acuerdo, activaré el sistema de seguridad. La ventana delantera está abierta.

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

Excepción de bloqueo sobre otro dispositivo que usa StatusReport

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

Lista de excepciones

Las siguientes excepciones producirán el TTS asociado en el dispositivo.