Errores y excepciones

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

Errores

Deberías mostrar un código de error cuando un problema cause una ejecución que la solicitud de consulta falle. Por ejemplo, si la cerradura de una puerta está atascada y no se puede bloqueado o desbloqueado, se debería 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 lámparas de un proveedor y las controla un concentrador, cuando el usuario pide apagar todas las luces, el proveedor puede devolver error a nivel del dispositivo si una sola luz no tiene conexión, o error a nivel global si toda la unidad central está sin conexión y no se puede controlar ninguna luz. Si todos los dispositivos sin conexión, no hay diferencia entre usar el nivel global o el nivel errores. Cuando un dispositivo no tiene conexión, debes informar el estado de {"online": false} en reportState aun si devuelvas el Código de error deviceOffline.

Resumen:

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

Errores a nivel global

El siguiente fragmento de JSON muestra cómo mostrar errores a nivel global en QUERY o EXECUTE.

Este es un ejemplo de un error de nivel global deviceOffline debido al concentrador: sin conexión:

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

Este es un ejemplo de un error de nivel global inSoftwareUpdate debido al concentrador: actualizando:

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

Errores a nivel del dispositivo

Respuesta de QUERY

El siguiente fragmento de JSON muestra cómo devolver errores a nivel de 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

El siguiente fragmento de JSON muestra cómo devolver errores a nivel de dispositivo en la 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

El siguiente fragmento de JSON muestra cómo informar errores a nivel del dispositivo en una notificaciones proactivas.

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

El siguiente fragmento de JSON 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 generarán el TTS asociado en el dispositivo.

Excepciones

Deberías devolver una excepción cuando haya un problema o una alerta asociados a un kubectl. El comando podría completarse con éxito o fallar.

Si el comando tuvo éxito (estado = "SUCCESS"), informa las excepciones usando la característica StatusReport (para dispositivos que no sean el objetivo) o devuelve un exceptionCode adecuado (para el dispositivo de destino).

Por ejemplo, si la pantalla de pelusa de la secadora está llena, el usuario puede iniciar su pero deberías advertirle sobre este estado. De forma similar, cuando un dispositivo tiene una batería baja que no está vacía, puedes ejecutar un comando pero deberías informarles que el dispositivo tiene poca batería.

Si el comando falla debido a excepciones, el estado debería ser "EXCEPTIONS", y las excepciones se deben informar mediante el trait StatusReport.

Excepción sin bloqueo (ÉXITO) sobre el dispositivo de destino

Este ejemplo se usa para trabar la puerta:

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

Este ejemplo se usa para activar un sistema de seguridad: Se activará el sistema de seguridad. La ventana frontal 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 con 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 generarán el TTS asociado en el dispositivo.