Solución de problemas de integración de Matter

fecha_de_actualización: 6-1-2023

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 una falla cuando se cumplen las intenciones del usuario, la canalización de Google Home Analytics registra esa falla en tus métricas y publica un registro de errores en los registros de tu proyecto.

Para solucionar los errores, debes seguir dos pasos:

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

Errores de supervisión

Puedes usar Google Cloud Monitoring dashboard 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 primero desde el que debes comenzar cuando supervises la confiabilidad de tus proyectos. Las caídas en este gráfico pueden indicar una interrupción para una parte o toda tu base de usuarios. Te recomendamos que supervises de cerca este gráfico para detectar irregularidades después de cada cambio o actualización de tu proyecto.
  • Los gráficos de Desglose de errores son más útiles cuando se trata de solucionar problemas en tus integraciones. Para cada error que se destaca 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 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 que no es 401 de tu servicio.

Usa requestId en Registros de GCP para verificar los registros del servicio de casa inteligente.
BACKEND_FAILURE_URL_TIMEOUT Se agotó el tiempo de espera de la solicitud de Google cuando se intentó comunicarse con tu servicio.

Verifica que tu servicio esté en línea, acepte conexiones y no esté por encima de su 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 Registros de GCP para verificar los registros del servicio de casa inteligente.
DEVICE_NOT_FOUND El dispositivo no existe en el servicio del socio.

Por lo general, esto indica una falla 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 formatos o valores no válidos en la carga útil.

Usa requestId en GCP Logging 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 observas un aumento en la frecuencia de este error en los registros de GCP, 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 observas un aumento en la frecuencia de este error en los registros de GCP, comunícate con nosotros para obtener más información.
GAL_NOT_FOUND Los tokens de acceso y de actualización del usuario almacenados en Google se invalidan y ya no se pueden actualizar. El usuario debe volver a vincular su cuenta para seguir usando tu servicio.

Si observas un aumento en la frecuencia de este error en los registros de GCP, comunícate con nosotros para obtener más información.
GAL_PERMISSION_DENIED Se produjo un error interno de Google cuando el uso compartido de tokens no está autorizado.

Si observas un aumento en la frecuencia de este error en los registros de GCP, comunícate con nosotros para obtener más información.
GAL_REFRESH_IN_PROGRESS El token de acceso del usuario venció y ya se está realizando otro intento simultáneo para actualizarlo.

Esto no es un problema y no se requiere 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 tu servicio lo invalidó. Usa requestId en el registro de GCP para verificar los registros del servicio de la casa inteligente.
INVALID_JSON La respuesta JSON no se puede analizar ni comprender.

Verifica la estructura de tu respuesta JSON en busca de sintaxis no válida, como corchetes que no coinciden, 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 un aumento en la frecuencia de este código, verifica si también observas un aumento en la frecuencia de errores relacionados con los intents de la 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 la respuesta de tu solicitud indica un error, asegúrate de usar uno de los que se proporcionan en nuestros códigos de error admitidos.
PARTNER_RESPONSE_INVALID_PAYLOAD El campo payload de respuesta no se puede analizar como un objeto JSON.

Verifica si el campo de carga útil en la respuesta de tu solicitud tiene paréntesis coincidentes y está estructurado correctamente como un campo JSON.
PARTNER_RESPONSE_INVALID_STATUS La respuesta no indica un estado o indica 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 para controlar errores y excepciones.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Faltan uno o más intents en la solicitud en la respuesta.

Verifica que tu respuesta de ejecución esté estructurada correctamente y que los resultados de todos los intents de la solicitud estén presentes en tu 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 correctamente y que todos los IDs de dispositivos de la solicitud estén presentes en tu respuesta.
PARTNER_RESPONSE_MISSING_PAYLOAD La respuesta no contiene un campo payload.

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

Verifica todos los campos de la respuesta de la solicitud en busca de caracteres no deseados, corchetes que no coincidan o errores de formato. Es posible que algunos caracteres Unicode no sean compatibles. Además, asegúrate de que tu respuesta esté correctamente estructura como un objeto JSON.
PROTOCOL_ERROR No se pudo 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 a partir del momento en que se envía la solicitud. Asegúrate de enviar una respuesta dentro de este período.
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 según los documentos de la casa inteligente y deben indicar el estado.
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 cae. También si no se pueden abrir conexiones nuevas a un servidor.

Registros de búsqueda

Una vez que te familiarices con la supervisión de tus integraciones mediante métricas, el siguiente paso es solucionar errores específicos mediante 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 intervalo de tiempo, recurso, gravedad de registro o entradas personalizadas.

Consulta registros de Cloud

Puedes usar los botones de consulta para crear tus filtros personalizados.

Cómo compilar 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 originan en el período seleccionado.

Para especificar un Recurso, haz clic en el menú desplegable Recurso y, luego, elige Proyecto de acción de 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, Información, Depuración y otros niveles de registro de gravedad.

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

Por ejemplo, la siguiente entrada personalizada mostrarí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 cómo consultar registros de manera eficaz.

Correcciones de pruebas

Una vez que identifiques los errores y apliques las actualizaciones para corregirlos, te recomendamos que pruebes tus correcciones en detalle con Google Home Test Suite. Proporcionamos una guía del usuario sobre cómo usar Test Suite, que te guía para probar tus cambios de manera eficaz.

Recursos de aprendizaje

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

Anterior
Cloud Logging para materia