Soluciona errores de integración

Google Cloud te proporciona las herramientas para supervisar la confiabilidad de los proyectos con Google Cloud Monitoring y depurar problemas con los registros de error Google Cloud Logging. Cuando se produce una falla cuando se entregan los intents del usuario, la canalización de Google Home Analytics registra ese error en tus métricas y publica un registro de error en los registros de tu proyecto.

Para solucionar los errores, sigue dos pasos:

  1. Supervisa el estado de tus proyectos con las métricas de casa inteligente.
  2. Para investigar los problemas, revisa las descripciones de errores detalladas en los registros de errores.

El proceso es similar para la integración local con Local Home SDK. Una vez que domines el flujo de solución de problemas, podrás alternar con facilidad entre las métricas y los registros para obtener estadísticas sobre tus errores.

Supervisa errores

Puedes usar Google Cloud Monitoring dashboard para acceder a las métricas de tu proyecto. Hay algunos gráficos clave que son especialmente útiles para supervisar la calidad y la depuración:

  • El gráfico de Tasa de éxito es el primer gráfico que comienza cuando supervisas la confiabilidad de los proyectos. Las disminuciones en este gráfico pueden indicar una interrupción en una parte o en toda tu base de usuarios. Te recomendamos que supervises atentamente este gráfico para detectar irregularidades después de cada cambio o actualización de tu proyecto.
  • El gráfico de Latencia del percentil 95 es un indicador importante del rendimiento de tu Acción de casa inteligente para los usuarios. Las fluctuaciones repentinas en este gráfico pueden indicar que tus sistemas no pueden ponerse al día con 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. Por cada error destacado en el gráfico de porcentaje de éxito, se muestra un código de error en el desglose de errores. Puedes ver los errores que marcó Google Home platform y cómo solucionarlos en la siguiente tabla.

Códigos de error de la plataforma

Estos son algunos códigos de error comunes que puedes ver en los registros de tu proyecto para identificar los problemas que detecta Google Home platform. Consulta la siguiente tabla para obtener información sobre la solución de problemas.

Código de error Descripción
BACKEND_FAILURE_URL_ERROR Google recibió un código de error HTTP 4xx distinto del 401 de tu servicio.

Usa requestId en Logging de GCP a fin de verificar los registros del servicio para el hogar inteligente.
BACKEND_FAILURE_URL_TIMEOUT Se agotó el tiempo de espera de la solicitud de Google al intentar acceder a tu servicio.

Verifica que el servicio esté en línea, que acepte conexiones y que no esté excedido de la capacidad. Además, verifica que el dispositivo de destino 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 Logging de GCP a fin de verificar los registros del servicio para el hogar inteligente.
DEVICE_NOT_FOUND El dispositivo no existe en el lado del servicio del socio.

Por lo general, esto indica un error en la sincronización de datos o una condición de carrera.
GAL_BAD_3P_RESPONSE Google no puede analizar la respuesta de tu servicio de vinculación de cuentas debido a valores o formatos no válidos en la carga útil.

Usa requestId en Logging de GCP para verificar los registros de errores en tu servicio de vinculación de cuentas.
GAL_INTERNAL Se produjo un error interno de Google cuando Google intentó recuperar un token de acceso.

Si ves una frecuencia mayor de este error en GCP Logging, comunícate con nosotros para obtener más información.
GAL_INVALID_ARGUMENT Se produjo un error interno de Google cuando Google intentó recuperar un token de acceso.

Si ves una frecuencia mayor de este error en GCP Logging, comunícate con nosotros para obtener más información.
GAL_NOT_FOUND Los tokens de acceso y los tokens de actualización del usuario almacenados en Google se invalidan y ya no se pueden actualizar. El usuario deberá volver a vincular su cuenta para seguir usando tu servicio.

Si ves una frecuencia mayor de este error en GCP Logging, comunícate con nosotros para obtener más información.
GAL_PERMISSION_DENIED Se produjo un error interno de Google cuando no se autorizó el uso compartido de tokens.

Si ves una frecuencia mayor de este error en GCP Logging, comunícate con nosotros para obtener más información.
GAL_REFRESH_IN_PROGRESS El token de acceso del usuario venció y ya hay otro intento simultáneo de actualización.

Esto no es un problema y no necesita realizar ninguna acción.
INVALID_AUTH_TOKEN Google recibió un código de error HTTP 401 de tu servicio.

El token de acceso no venció, pero el servicio lo invalidó. Usa requestId en GCP Logging para verificar los registros del servicio de casa inteligente.
INVALID_JSON No se puede analizar o comprender la respuesta JSON.

Revisa la estructura de tu respuesta JSON en busca de sintaxis no válida, como corchetes, comas faltantes o caracteres no válidos.
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 una mayor frecuencia de este código, comprueba si también ves una tasa más alta de errores relacionados con los intents de casa inteligente o las solicitudes de tokens de actualización.
PARTNER_RESPONSE_INVALID_ERROR_CODE La respuesta indica un código de error no reconocido.

Si tu respuesta a la solicitud indica un error, asegúrate de usar uno de los códigos de error admitidos.
PARTNER_RESPONSE_INVALID_PAYLOAD No se puede analizar el campo de respuesta payload como un objeto JSON.

Verifica si el campo de carga útil en tu respuesta de solicitud tiene corchetes y está estructurado de forma correcta como un campo JSON.
PARTNER_RESPONSE_INVALID_STATUS La respuesta no indica un estado, o bien uno incorrecto.

Las respuestas a las solicitudes de entrega de intents deben indicar un estado con SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Puedes encontrar más información sobre cómo manejar errores y excepciones.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Faltan uno o más intents presentes en la solicitud en la respuesta.

Verifica que tu respuesta de ejecución esté estructurada de manera correcta y que los resultados de todos los intents de la solicitud estén presentes en la respuesta.
PARTNER_RESPONSE_MISSING_DEVICE Faltan uno o más dispositivos presentes en la solicitud en la respuesta.

Verifica que tu respuesta de ejecución esté estructurada de manera correcta y que todos los ID de dispositivo de la solicitud estén presentes en la respuesta.
PARTNER_RESPONSE_MISSING_PAYLOAD La respuesta no contiene un campo payload.

Asegúrate de incluir un campo de carga útil en tu respuesta de solicitud. Puedes obtener más información para compilar correctamente una respuesta de ejecución.
PARTNER_RESPONSE_NOT_OBJECT No se puede analizar la respuesta como un objeto JSON.

Revisa todos los campos de tu respuesta a la solicitud para detectar caracteres no deseados, corchetes que no coinciden o errores de formato. Es posible que algunos caracteres Unicode no sean compatibles. Además, asegúrate de que tu respuesta esté estructurada de manera correcta como un objeto JSON.
PROTOCOL_ERROR Se produjo un error al procesar la solicitud.

Usa requestId en Google Cloud Logging para verificar los registros del servicio de casa inteligente.
RESPONSE_TIMEOUT Se agotó el tiempo de espera de la solicitud mientras se esperaba la respuesta.

El tiempo de espera para enviar una respuesta es de 9 segundos desde el momento en que se envía la solicitud. Asegúrate de enviar una respuesta dentro de este plazo.
RESPONSE_UNAVAILABLE No se recibe ninguna respuesta o la respuesta no indica el estado.

Las respuestas a las solicitudes de entrega de intents deben estructurarse de acuerdo con los documentos de la casa inteligente y, además, indicar el estado.
TRANSIENT_ERROR Un error transitorio es un error que se resolverá solo.

Por lo general, estos errores se manifiestan como una conexión a un dispositivo o servicio que se pierde. También ocurre si no se pueden abrir nuevas conexiones a un servidor.

Registros de búsqueda

Una vez que te sientas cómodo para supervisar tus integraciones con métricas, el siguiente paso es solucionar errores 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 detalles sobre 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 las que necesitas. Las consultas se pueden basar en un Intervalo de tiempo, un Recurso, la Gravedad de registro o entradas personalizadas.

Consulta registros de Cloud

Puedes usar los botones de búsqueda para crear tus filtros personalizados.

Crea consultas de registros de Cloud

Para especificar un Intervalo de tiempo, haz clic en el botón de selección de intervalo de tiempo y elige una de las opciones proporcionadas. Esto filtrará los registros y mostrará los que se originen en el intervalo de tiempo seleccionado.

Para especificar un Recurso, haz clic en el menú desplegable Recurso y, luego, selecciona Proyecto de acción del Asistente de Google. 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, Info, Debug y otros niveles de registro de gravedad.

También puedes usar el campo Consulta en Logs Explorer para ingresar entradas personalizadas. El motor de consultas que se usa en este campo admite consultas básicas, como la coincidencia de strings, y tipos de consultas más avanzados, incluidos comparadores (<, >=, !=) y operadores booleanos (AND, OR, NOT).

Por ejemplo, la siguiente entrada personalizada mostraría errores que se originaron 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 de manera eficaz.

Pruebas de correcciones

Una vez que identifiques los errores y apliques 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, en la que se explica cómo probar los cambios de manera efectiva.

Recursos de aprendizaje

En este documento, se proporcionan los pasos para solucionar errores de tu Acción de casa inteligente. También puedes consultar nuestros codelabs para obtener más información sobre la depuración: