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 cuando se cumplen 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.
Sigue estos dos pasos para solucionar los errores:
- Supervisa el estado de tus proyectos con las métricas de casa inteligente.
- Investiga los problemas revisando 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.
Errores de supervisión
Puedes usar Google Cloud Monitoring dashboards para acceder a las métricas de tu proyecto. Existen algunos gráficos clave que son especialmente útiles para supervisar la calidad y depurar:
- El gráfico Tasa de éxito es el primer gráfico que debes consultar cuando supervisas la confiabilidad de tus proyectos. Las caídas 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 Latencia del percentil 95 es un indicador importante del rendimiento de tu integración de Cloud-to-cloud para tus usuarios. Las fluctuaciones repentinas en este gráfico pueden indicar que tus sistemas no pueden mantenerse al día con las solicitudes. Se recomienda revisar este gráfico de forma periódica 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. Por 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 el Google Home platform y cómo solucionar problemas.
Códigos de error comunes de la plataforma
A continuación, se muestran algunos códigos de error comunes que puedes ver en los registros de tu proyecto para identificar los problemas que detectó el 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 |
|---|---|---|
AGENT_ISSUE |
Se produjo un problema general con el agente de nube del socio.
Verifica si hay excepciones no controladas o fallas en tus registros de entrega. |
Sí |
AGENT_UNAVAILABLE_ERROR |
Google no pudo acceder a la URL de entrega del socio.
Asegúrate de que el servidor esté en línea, de que el firewall no bloquee a Google y de que la URL sea correcta. |
Sí |
COMMAND_FAILED |
Se produjo una falla genérica durante la ejecución de un comando.
Revisa tus registros de entrega para el requestId específico
y encontrar la causa raíz.
|
Sí |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google recibió un error HTTP 4xx (que no es 401) de tu
fulfillment.
Revisa los registros del servidor web para ver si hay respuestas 403, 404 o 400. |
Sí |
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT |
Se agotó el tiempo de espera de la solicitud de Google cuando intentó comunicarse con tu servicio.
Verifica que tu servicio esté en línea, acepte conexiones y no supere la capacidad. Además, verifica que el dispositivo de destino esté encendido, en línea y sincronizado. |
Sí |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
La URL de entrega está bloqueada por robots.txt o filtros de seguridad.
Asegúrate de que los rastreadores o servicios de Google puedan acceder a tu extremo de entrega. |
Sí |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google recibió un error HTTP 5xx de tu servicio de entrega.
Asegúrate de que el servicio de la URL del extremo sea estable, correcto y de acceso público, y de que el servicio esté en ejecución. Usa el requestId en
Google Cloud Logging para verificar los registros de tu servicio de casa inteligente.
Agrega verificaciones de estado y control de reintentos.
Investigar fallas del servidor, tiempos de espera o errores de puerta de enlace 502/503
|
Sí |
EXECUTION_BAILOUT_INVALID_RESPONSE |
La respuesta JSON tenía un formato tan incorrecto que se anuló el procesamiento.
Usa un validador de JSON para asegurarte de que tu respuesta siga estrictamente los esquemas de intents. |
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 las características requeridas. |
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_NOT_FOUND |
Los tokens de acceso y actualización del usuario almacenados en Google no son válidos o
no se pueden actualizar, lo que impide la autenticación y el acceso al
servicio del socio.
Asegúrate de que los tokens sigan siendo válidos y estén sincronizados, controla los cambios de estado de la cuenta de forma adecuada y solicita a los usuarios que vuelvan a vincular la cuenta si se confirma que se revocaron los tokens. |
|
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
La integración se encuentra en estado de solo lectura del lado del socio.
Verifica 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). Asegúrate de que el servidor de OAuth del socio responda correctamente a las solicitudes de refresh_token de Google para emitir nuevos tokens de acceso sin problemas.
|
Sí |
EXECUTION_INVALID_JSON |
Google no pudo analizar la carga útil de la respuesta JSON.
Verifica si hay errores de sintaxis, corchetes faltantes o caracteres no válidos en tu respuesta. |
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 el requestId en Google Cloud Logging para verificar los registros del servicio de tu 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í |
MALFORMED_JSON |
La estructura JSON está dañada (por ejemplo, cadenas u objetos sin cerrar).
Asegúrate de que tu entrega use una biblioteca JSON estándar para serializar las respuestas. |
Sí |
NOT_IMPLEMENTED |
El socio no implementó el intent o el atributo solicitados.
Solo incluye en tu respuesta de SYNC los atributos que hayas
implementado por completo.
|
Sí |
OPEN_AUTH_FAILURE |
El token de acceso del usuario venció y Google no puede actualizarlo,
o Google recibió un código de error HTTP 401 de tu servicio.
Si ves un aumento en la tasa de este código, verifica si también ves un aumento en la tasa 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 devuelve no está en la lista de idiomas admitidos por 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 entrega. |
Sí |
PARTNER_RESPONSE_INVALID_STATUS |
La respuesta status no fue SUCCESS, ERROR ni OFFLINE.
Asegúrate de que cada resultado de 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.
Valida la estructura de tu respuesta con la documentación para desarrolladores de Google Home. Asegúrate de que la respuesta no se trunque ni devuelva un cuerpo vacío debido a un error interno del servidor. 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 que solicitó Google.
Asegúrate de que tu respuesta incluya cada ID proporcionado en la
carga útil de la solicitud.
|
Sí |
PARTNER_RESPONSE_MISSING_PAYLOAD |
A la respuesta le falta el campo obligatorio payload.
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. Asegúrate de que payload.commands[] sea un objeto JSON
adecuado con IDs, estado y estados opcionales.
|
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 si hay aumentos repentinos y comunícate con el equipo de asistencia. |
Sí |
RESOURCE_UNAVAILABLE |
El recurso solicitado (dispositivo o atributo) no está disponible.
Verifica si el dispositivo está "Ocupado" o si se inhabilitó temporalmente. |
Sí |
RESPONSE_TIMEOUT |
El servicio de entrega no respondió en un plazo de 9 segundos.
Optimiza la latencia del backend; 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 entrega del socio.
Verifica que el servicio se esté ejecutando y que el extremo no falle. |
Sí |
TIMEOUT |
Se agotó el tiempo de espera general mientras se procesaba el intent.
Verifica los registros para ver si hay tiempos de espera de servicio internos entre la nube y los concentradores de dispositivos. |
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 errores es una entrada similar a JSON con campos que contienen información útil, como la hora, el código de error y los detalles relacionados con el intent 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 se pueden basar 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 originan en el período seleccionado.
Para especificar un Recurso, haz clic en el menú desplegable Recurso y, luego, elige Proyecto de Acciones de Asistente de Google. Esto agrega un filtro en 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 Consulta en el Logs Explorer
para ingresar entradas personalizadas. El motor de consultas que usa este campo admite consultas básicas, como la coincidencia de cadenas, y tipos de consultas más avanzados, incluidos los comparadores (<, >=, !=) y los operadores booleanos (AND, OR, NOT).
Por ejemplo, la entrada personalizada que aparece a continuación 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 de consultas de registros eficaces.
Prueba las correcciones
Una vez que identifiques los errores y apliques las actualizaciones para corregirlos, te recomendamos que pruebes las correcciones de forma exhaustiva con Google Home Test Suite. Proporcionamos una guía del usuario sobre cómo usar Test Suite, que te guiará para probar tus cambios de manera eficaz.
Recursos de aprendizaje
En este documento, se proporcionan los pasos para solucionar problemas de errores en tu Acción de casa inteligente. También puedes consultar nuestros codelabs para obtener más información sobre la depuración:
- Codelab Cómo depurar una casa inteligente: Es una guía de inicio rápido para depurar la integración de la casa inteligente en la nube.
- Codelab Cómo depurar Local Home: Es una guía de inicio rápido para depurar la integración local de la casa inteligente.