Google Cloud te proporciona las herramientas para supervisar la confiabilidad de tus proyectos con Google Cloud Monitoring y depurar problemas con los registros de errores de Google Cloud Logging. Cada vez que se produce un error al satisfacer las intenciones del usuario, la canalización de Google Home Analytics registra ese error en tus métricas y publica un registro de errores en los registros de tu proyecto.
Para solucionar los errores, sigue estos dos pasos:
- Supervisa el estado de tus proyectos con métricas de casa inteligente.
- Investiga los problemas verificando las descripciones detalladas de los errores en los registros de errores.
De manera opcional, puedes probar tu Acción compartiéndola con otros usuarios. Asegúrate de controlar los errores y las excepciones de forma adecuada.
Supervisa los errores
Puedes usar Google Cloud Monitoring dashboards para acceder a las métricas de tu proyecto. Hay algunos gráficos clave que son especialmente útiles para supervisar la calidad y depurar:
- El gráfico de Tasa de éxito es el primero que debes consultar cuando supervisas la confiabilidad de tus proyectos. Las disminuciones en este gráfico pueden indicar una interrupción para una parte o la totalidad de tu base de usuarios. Te recomendamos que supervises de cerca este gráfico para detectar cualquier irregularidad después de cada cambio o actualización en tu proyecto.
- El gráfico de latencia del percentil 95 es un indicador importante del rendimiento de tu integración de Cloud-to-cloud para los usuarios. Las fluctuaciones repentinas en este gráfico pueden indicar que tus sistemas no pueden satisfacer las solicitudes. Se recomienda revisar este gráfico periódicamente para detectar cualquier comportamiento inesperado.
- Los gráficos de Desglose de errores son más útiles cuando se trata de solucionar problemas en tus integraciones. Para cada error destacado en el gráfico de porcentaje de éxito, se muestra un código de error en el desglose de errores. En la siguiente tabla, puedes ver los errores marcados por Google Home platform y cómo solucionarlos.
Códigos de error comunes de la plataforma
Estos son algunos códigos de error comunes que puedes ver en los registros de tu proyecto para identificar los problemas detectados por Google Home platform. Consulta la siguiente tabla para obtener información sobre la solución de problemas. Para obtener una lista completa de los códigos de error, consulta Errores y excepciones.
| Código de error | Descripción | Acción del socio |
|---|---|---|
ACTION_NOT_AVAILABLE |
El comando no es válido para el estado actual del dispositivo (por ejemplo, "Establecer temperatura" mientras el dispositivo está apagado).
Verifica los rasgos del dispositivo y la lógica del estado actual en tu cumplimiento. |
Sí |
AGENT_ISSUE |
Se produjo un problema general con el agente de Cloud del socio.
Verifica si hay excepciones o fallas no controladas en los registros de cumplimiento. |
Sí |
AGENT_UNAVAILABLE_ERROR |
Google no pudo acceder a la URL de cumplimiento del socio.
Asegúrate de que tu servidor esté en línea, de que el firewall no bloquee a Google y de que la URL sea correcta. |
Sí |
APP_LAUNCH_FAILED |
No se pudo iniciar la app de terceros en el dispositivo de destino.
Verifica el appId y que la app sea compatible con el hardware de destino. |
Sí |
AUTH_EXPIRED |
El token de acceso de OAuth venció y no se puede actualizar.
Verifica la rotación del token de actualización y asegúrate de que el usuario no haya revocado el acceso. |
Sí |
BACKEND_FAILURE_URL_TIMEOUT |
Se agotó el tiempo de espera de la solicitud de Google al intentar acceder a tu servicio.
Verifica que tu servicio esté en línea, acepte conexiones y no esté sobrecargado. Además, verifica que el dispositivo objetivo esté encendido, en línea y sincronizado. |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google recibió un código de error HTTP 5xx de tu servicio.
Usa requestId en Cloud Logging de Google Cloud para verificar
los registros de tu servicio para la casa inteligente.
|
|
CHANNEL_SWITCH_FAILED |
El dispositivo no pudo cambiar al canal de medios solicitado.
Verifica los nombres o números de los canales y el estado de suscripción del usuario. |
Sí |
CHARGER_ISSUE |
El dispositivo informa un problema de hardware con su sistema de carga.
El socio debe investigar la telemetría a nivel del hardware y el estado de la batería. |
Sí |
CHECK_PARTNER_APP |
El error requiere que el usuario abra la app del socio para resolverlo.
Usa este código para los errores que requieren una interacción compleja de la IU (por ejemplo, actualizaciones de firmware). |
Sí |
COMMAND_FAILED |
Se produjo un error genérico durante la ejecución de un comando.
Revisa tus registros de cumplimiento para encontrar el requestId específico
y determinar la causa raíz.
|
Sí |
COMMAND_INSERT_FAILED |
Google no pudo poner en cola ni procesar el comando para el dispositivo.
Investiga el rendimiento de escritura de la base de datos o la lógica interna de filas de comandos. |
Sí |
DEVICE_NOT_FOUND |
El ID del dispositivo en la solicitud no existe en el socio.
Asegúrate de que tu nube active un requestSync cuando un usuario
agregue o borre dispositivos.
|
Sí |
ERROR_STATUS |
La respuesta indicó un estado de "ERROR" no específico sin un código.
Siempre incluye una cadena de errorCode específica para mejorar
los datos del panel y de TTS del usuario.
|
Sí |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google recibió un error HTTP 4xx (que no es 401) de tu
fulfillment.
Revisa los registros de tu servidor web para ver si hay respuestas 403, 404 o 400. |
Sí |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
La URL de cumplimiento está bloqueada por robots.txt o filtros de seguridad.
Asegúrate de que se pueda acceder a tu extremo de cumplimiento desde los rastreadores o servicios de Google. |
Sí |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google recibió un error HTTP 5xx de tu servicio de cumplimiento.
Investiga bloqueos, tiempos de espera o errores de puerta de enlace 502/503 del servidor. |
Sí |
EXECUTION_BAILOUT_INVALID_RESPONSE |
La respuesta JSON tenía un formato tan incorrecto que se interrumpió el procesamiento.
Usa un validador de JSON para asegurarte de que tu respuesta siga estrictamente los esquemas de intención. |
Sí |
EXECUTION_GAL_BAD_3P_RESPONSE |
No se pudo vincular la cuenta debido a un formato no válido en la respuesta del token.
Verifica que el formato de respuesta de tu servidor de OAuth coincida con los requisitos de Google. |
Sí |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
La cuenta del usuario no tiene los permisos necesarios para realizar esta acción.
Verifica los permisos solicitados durante OAuth y asegúrate de que coincidan con los rasgos requeridos. |
Sí |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
La nube del socio indica que el usuario desvinculó su cuenta.
Asegúrate de que tu asignación de agentUserId sea estable y no se haya
borrado.
|
Sí |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
La integración se encuentra en estado de solo lectura en el socio.
Comprueba si la cuenta del usuario está suspendida o en modo de mantenimiento de "solo lectura". |
Sí |
EXECUTION_GAL_UNLINKED_BY_3P |
El servicio de terceros desvinculó la cuenta de forma proactiva.
Investiga por qué se desconectó al usuario (por ejemplo, restablecimiento de seguridad). |
Sí |
EXECUTION_INVALID_JSON |
Google no pudo analizar la carga útil de la respuesta JSON.
Comprueba si hay errores de sintaxis, falta de corchetes o caracteres no válidos en tu respuesta. |
Sí |
FAULTY_BATTERY |
El hardware del dispositivo informa que la batería está fallando o agotada.
Indica al usuario que reemplace la batería física con TTS o la app. |
Sí |
FUNCTION_NOT_SUPPORTED |
El dispositivo no admite el modo o la función solicitados.
Asegúrate de que la respuesta de SYNC refleje con precisión las
capacidades del dispositivo.
|
Sí |
HARD_ERROR |
Es un error no transitorio que no se resolverá sin intervención manual.
Úsalo para fallas de hardware permanentes o estados de cuenta irrecuperables. |
Sí |
INVALID_AUTH_TOKEN |
Google recibió un código de error HTTP 401 de tu servicio.
El token de acceso no venció, pero tu servicio lo invalidó. Usa requestId en Cloud Logging de Google Cloud para verificar los registros de tu servicio de casa inteligente.
|
|
INVALID_JSON |
La estructura de la respuesta no es válida (por ejemplo, faltan campos obligatorios).
Valida tu respuesta con los esquemas JSON de intención. |
Sí |
LOCK_FAILURE |
La cerradura inteligente no pudo cambiar al estado solicitado.
Investiga si hay atascos físicos, batería baja o fallas en el motor del hardware de la cerradura. |
Sí |
MALFORMED_JSON |
La estructura JSON está dañada (por ejemplo, cadenas o objetos sin cerrar).
Asegúrate de que tu entrega use una biblioteca JSON estándar para serializar las respuestas. |
Sí |
MISSING_STATE |
La respuesta de QUERY no contenía el estado del dispositivo solicitado.
Asegúrate de que todos los rasgos definidos en SYNC se tengan en cuenta en
cada respuesta de QUERY.
|
Sí |
NETWORK_PROFILE_NOT_RECOGNIZED |
El dispositivo no reconoce el perfil de red solicitado.
Verifica que la cadena del nombre del perfil coincida con los perfiles admitidos en la respuesta de SYNC.
|
Sí |
NOT_IMPLEMENTED |
El socio no implementó el rasgo o el intent solicitado.
Solo incluye en tu respuesta de SYNC los rasgos que hayas
implementado por completo.
|
Sí |
OAUTH_RECONNECT_CALL_TO_ACTION |
Activa una notificación para que el usuario vuelva a vincular su cuenta.
Usa este valor cuando se invalida la sesión de un usuario y se requiere una reautenticación manual de OAuth. |
Sí |
OPEN_AUTH_FAILURE |
El token de acceso del usuario venció y Google no puede actualizarlo, o bien Google recibió un código de error HTTP 401 de tu servicio.
Si observas un aumento en la frecuencia de este código, verifica si también ves un aumento en la frecuencia de errores relacionados con intents de casa inteligente o solicitudes de tokens de actualización. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
La cadena errorCode que se devolvió no se encuentra en la lista de formatos compatibles de Google.
Asigna tus errores internos a la Lista de errores oficial. |
Sí |
PARTNER_RESPONSE_INVALID_PAYLOAD |
El campo payload de la respuesta no es un objeto JSON válido.
Verifica la estructura raíz de tu respuesta de cumplimiento. |
Sí |
PARTNER_RESPONSE_INVALID_STATUS |
La respuesta status no fue SUCCESS, ERROR ni OFFLINE.
Asegúrate de que cada resultado del dispositivo en tu respuesta incluya una cadena de estado válida. |
Sí |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
La respuesta no incluyó resultados para todos los comandos o dispositivos solicitados.
Cada elemento del array commands de la solicitud debe tener una
entrada de respuesta correspondiente.
|
Sí |
PARTNER_RESPONSE_MISSING_DEVICE |
Se omitió de la respuesta un dispositivo específico solicitado por Google.
Asegúrate de que tu respuesta incluya cada ID proporcionado en la
carga útil de la solicitud.
|
Sí |
PARTNER_RESPONSE_MISSING_PAYLOAD |
Falta el campo obligatorio payload en la respuesta.
Asegúrate de que tu objeto JSON de nivel superior incluya una clave payload.
|
Sí |
PARTNER_RESPONSE_NOT_OBJECT |
No se pudo analizar toda la respuesta como un objeto JSON.
Verifica si hay caracteres finales o contenido que no sea JSON en el cuerpo de la respuesta HTTP. |
Sí |
PROTOCOL_ERROR |
Se produjo un error en el protocolo de comunicación subyacente.
Investiga los problemas de encabezado HTTP o las fallas en el protocolo de enlace SSL/TLS. |
Sí |
RELINK_REQUIRED |
El usuario debe volver a vincular su cuenta para seguir usando la integración.
Asegúrate de que tu servidor muestre este código cuando un token de actualización sea inválido de forma permanente. |
Sí |
REQUEST_ID_NOT_FOUND |
Google no pudo encontrar el ID de seguimiento interno de la solicitud.
Por lo general, se trata de un error interno de la plataforma. Supervisa los picos y comunícate con el equipo de asistencia. |
Sí |
RESOURCE_UNAVAILABLE |
El recurso solicitado (dispositivo o rasgo) no está disponible.
Comprueba si el dispositivo está "Ocupado" o se inhabilitó temporalmente. |
Sí |
RESPONSE_TIMEOUT |
El servicio de cumplimiento no respondió en un plazo de 9 segundos.
Optimiza la latencia del backend y verifica si hay consultas lentas a la base de datos o retrasos en la red regional. |
Sí |
RESPONSE_UNAVAILABLE |
No se recibió respuesta de la URL de cumplimiento del socio.
Verifica que tu servicio esté en ejecución y que el extremo no falle. |
Sí |
SCENE_CANNOT_BE_APPLIED |
No se pudo activar la escena solicitada (por ejemplo, faltan dispositivos).
Verifica el estado interno de las escenas del usuario en la nube del socio. |
Sí |
STREAM_UNPLAYABLE |
No se pudo iniciar o falló la transmisión de la cámara.
Verifica la señalización de WebRTC/HLS y asegúrate de que la URL de la transmisión sea válida. |
Sí |
TIMEOUT |
Se produjo un tiempo de espera general mientras se procesaba la intención.
Verifica los registros de los tiempos de espera internos del servicio entre tus centros de dispositivos y de la nube. |
Sí |
TRANSIENT_ERROR |
Un error transitorio es un error que se resolverá por sí solo.
Por lo general, estos errores se manifiestan como una conexión a un dispositivo o servicio que se interrumpe. También si no se pueden abrir conexiones nuevas a un servidor. |
|
UNABLE_TO_LOCATE_DEVICE |
No se pudo encontrar el dispositivo con el rasgo Locator (por ejemplo, falló el ping).
Verifica la conectividad local del dispositivo (Wi-Fi o Bluetooth). |
Sí |
UNABLE_TO_RING_DEVICE |
Se accedió al dispositivo, pero no se pudo activar su función de alerta o llamada.
Verifica el estado de alerta o del altavoz del hardware y los niveles de volumen. |
Sí |
UNABLE_TO_SILENCE_DEVICE |
El dispositivo no pudo detener la alerta o el sonido activos.
Investiga las fallas de comunicación entre la nube y el dispositivo físico. |
Sí |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
Se produjo un error imprevisto. El usuario debe verificar la app del socio.
Úsalo como un recurso general para los errores que no tienen un equivalente específico compatible con Google. |
Sí |
UNKNOWN_ERROR |
Es un error genérico sin detalles adicionales.
El objetivo es reemplazarlo por códigos de error más específicos para mejorar la solución de problemas. |
Sí |
UNLOCK_FAILURE |
La cerradura inteligente no pudo alcanzar el estado "Destrabada".
Investiga los atascos de hardware, la batería baja o las entradas de PIN no válidas. |
Sí |
Registros de búsqueda
Una vez que te sientas cómodo supervisando tus integraciones con métricas, el siguiente paso es solucionar problemas específicos con Cloud Logging. Un registro de error es una entrada similar a JSON con campos que contienen información útil, como la hora, el código de error y los detalles sobre la intención de casa inteligente de origen.
Hay varios sistemas dentro de Google Cloud que envían registros a tu proyecto en todo momento. Debes escribir consultas para filtrar tus registros y encontrar los que necesitas. Las consultas pueden basarse en un período, un recurso, la gravedad del registro o entradas personalizadas.
Puedes usar los botones de consulta para crear tus filtros personalizados.
Para especificar un período, haz clic en el botón de selección de período y elige una de las opciones proporcionadas. Esto filtrará los registros y mostrará los que se originaron en el período seleccionado.
Para especificar un Recurso, haz clic en el menú desplegable Recurso y, luego, elige Proyecto de acción de Google Assistant. Esto agrega un filtro a tu consulta para mostrar los registros que se originan en tu proyecto.
Usa el botón Gravedad para filtrar por Emergencia, Información, Depuración y otros niveles de gravedad de los registros.
También puedes usar el campo Query en Logs Explorer para ingresar entradas personalizadas. El motor de consultas que usa este campo admite tanto consultas básicas, como la coincidencia de cadenas, como tipos de consultas más avanzadas, incluidos comparadores (<, >=, !=) y operadores booleanos (AND, OR, NOT).
Por ejemplo, la siguiente entrada personalizada devolvería errores que se originan en un tipo de dispositivo LIGHT:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
Visita la biblioteca de consultas para encontrar más ejemplos para consultar registros de manera eficaz.
Prueba de correcciones
Una vez que identifiques los errores y apliques las actualizaciones para corregirlos, te recomendamos que pruebes las correcciones a fondo con Google Home Test Suite. Proporcionamos una guía del usuario sobre cómo usar Test Suite, que te explica cómo probar tus cambios de manera eficaz.
Recursos de aprendizaje
En este documento, se proporcionan los pasos para solucionar problemas en tu acción para la casa inteligente. También puedes consultar nuestros codelabs para obtener más información sobre la depuración:
- Codelab de depuración de casa inteligente: Guía de inicio rápido para depurar la integración en la nube de la casa inteligente.
- Codelab de depuración de Local Home: Guía de inicio rápido para depurar la integración local de la casa inteligente.