Errores y excepciones

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

Errores

Debes devolver un código de error cuando un problema hace que falle una solicitud de ejecución o consulta. Por ejemplo, si una cerradura de puerta está trabada y no se puede trabar ni destrabar, se debe devolver 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 estas se controlan con un concentrador, cuando el usuario pida 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 puede controlar ninguna luz. 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 de 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 de nivel global en la respuesta de QUERY o EXECUTE.

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

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

Un ejemplo de error de nivel global inSoftwareUpdate debido a que el concentrador se está actualizando es el siguiente:

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

En el siguiente fragmento de JSON, se muestra cómo devolver errores a nivel del dispositivo en la respuesta 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 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 el TTS asociado 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 con un comando. El comando podría tener éxito o fallar.

Si el comando se ejecutó correctamente (status = "SUCCESS"), informa las excepciones con la característica StatusReport (para dispositivos que no sean el de destino) o devolviendo un exceptionCode adecuado (para el dispositivo de destino).

Por ejemplo, si el filtro de pelusas de la secadora está lleno, el usuario puede iniciar la secadora, pero es posible que quieras advertirle sobre este estado. Del mismo modo, cuando un dispositivo tiene poca batería, pero no está agotada, puedes ejecutar un comando, pero debes informar 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 atributo StatusReport.

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

Este ejemplo es para trabar la puerta:

La cerradura de la puerta principal tiene poca batería. Trabaré 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 sin bloqueo (SUCCESS) sobre otro dispositivo que usa StatusReport

Este ejemplo es para activar un sistema de seguridad: De acuerdo, activando 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.