Solución de problemas de integración de Matter

refresh_date: 2023-01-06

Google Cloud te proporciona las herramientas para supervisar la confiabilidad de tus proyectos con Google Cloud Monitoring y depurar problemas con Google Cloud Logging registros de errores. Cuando se produce una falla al cumplir con las intents 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, sigue estos dos pasos:

  1. Supervisa el estado de tus proyectos con métricas de casa inteligente.
  2. Investiga los problemas consultando las descripciones detalladas de los errores en los registros de errores.

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 errores:

  • El gráfico de tasa de éxito es el primero 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 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 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 la 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 la nube del socio.

Verifica si hay excepciones o fallas no controladas en tus 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, que el firewall no bloquee a Google y que la URL sea correcta. 		Sí
BACKEND_FAILURE_URL_TIMEOUT Se agotó el tiempo de espera de la solicitud de Google cuando intentó acceder a tu servicio.

Verifica que tu servicio esté en línea, acepte conexiones, y no esté sobrecargado. 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 el requestId en Google Cloud Logging para consultar los registros de tu servicio de casa inteligente. Investiga las fallas del servidor, los tiempos de espera, o los errores de puerta de enlace 502/503.
COMMAND_FAILED Se produjo una falla genérica durante la ejecución de un comando.

Consulta tus registros de cumplimiento para obtener el requestId para encontrar la causa raíz. 		Sí
EXECUTION_BACKEND_FAILURE_URL_ERROR Google recibió un error HTTP 4xx (que no sea 401) de tu cumplimiento.

Consulta los registros de tu servidor web para obtener respuestas 403, 404 o 400. 		Sí
EXECUTION_BACKEND_FAILURE_URL_ROBOTED El archivo robots.txt o los filtros de seguridad bloquean la URL de cumplimiento.

Asegúrate de que los rastreadores o servicios de Google puedan acceder a tu extremo de cumplimiento. 		Sí
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google recibió un error HTTP 5xx de tu servicio de cumplimiento.

Asegúrate de que el servicio de URL del extremo sea estable, correcto y accesible de forma pública, y que el servicio esté en ejecución. Agrega verificaciones de estado y control de reintentos. Investiga las fallas del servidor, los tiempos de espera o los 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 los atributos 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_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. 		Sí
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P La integración se encuentra en estado de solo lectura en el 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ó el usuario (por ejemplo, restablecimiento de seguridad). Asegúrate de que el servidor de OAuth del socio responda correctamente a las solicitudes refresh_token de Google para emitir tokens de acceso nuevos 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 consultar 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 intents. 		Sí
MALFORMED_JSON La estructura JSON está dañada (por ejemplo, cadenas o objetos).

Asegúrate de que tu cumplimiento use una biblioteca JSON estándar para serializar respuestas. 		Sí
NOT_IMPLEMENTED El socio no implementó la intent o el atributo solicitados.

Incluye solo los atributos en tu respuesta SYNC que hayas implementado por completo. 		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 ves un aumento en la tasa de este código, verifica si también ves un aumento en la tasa de errores relacionados con las intents de casa inteligente o las solicitudes de token de actualización.
PARTNER_RESPONSE_INVALID_ERROR_CODE La cadena errorCode que se muestra no está en la lista admitida 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 El status de la respuesta no era 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.

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 muestre un cuerpo vacío debido a un error interno del servidor. Cada elemento en el 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. 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, es un error interno de la plataforma. Supervisa los 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 se inhabilitó temporalmente. 		Sí
RESPONSE_TIMEOUT El servicio de cumplimiento no respondió en 9 segundos.

Optimiza la latencia del backend. Verifica si hay consultas lentas de la base de datos o retraso 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í
TIMEOUT Se produjo un tiempo de espera general durante el procesamiento de la intent.

Consulta los registros para ver los tiempos de espera del servicio interno entre tu nube y los hubs 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 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 los detalles sobre la 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 pueden basarse en un intervalo de tiempo, recurso, la gravedad del registro o entradas personalizadas.

Consulta registros de Cloud

Puedes usar los botones de consulta para ayudarte a 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 originan en el intervalo de tiempo 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 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 del registro.

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 comparadores (<, >=, !=) y operadores booleanos (AND, OR, NOT).

Por ejemplo, la siguiente entrada personalizada mostraría los 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 las correcciones

Una vez que identifiques los errores y apliques las actualizaciones para corregirlos, te recomendamos que pruebes tus correcciones minuciosamente 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