Google Home Vitals (Cloud)

Este conjunto de paneles y alertas te ayuda a mantener de forma proactiva una integración de alta calidad con el ecosistema de Google Home. Google se compromete a ayudar a los socios a desarrollar un ecosistema de alta calidad para todos los clientes.

El panel tiene tres secciones, cada una de las cuales abarca una parte clave que contribuye a la calidad de una integración general.

1. Métricas de Google al socio : Mide el estado de las llamadas de Google a tu backend de la nube.

2. Estado del sistema: Métricas del socio a Google : Mide el estado de las llamadas de tu sistema a Google.

3. Estado del dispositivo: Exactitud del estado : Mide la exactitud de los estados almacenados en los sistemas de Google, que se usan para atender las consultas de los usuarios.

Cuando las métricas no cumplen con sus valores objetivo, se destacan en rojo para indicar un problema que podría afectar la experiencia del usuario. La siguiente información proporciona detalles sobre cada objetivo y por qué es importante para tus usuarios.

Si el siguiente botón no te lleva directamente al panel, puedes acceder a él seleccionando la página Descripción general , luego Paneles y, por último, Panel de estadísticas de Google Home (Cloud) en la lista Mis paneles para ver tu panel.

Ir al panel

Métricas de Google al socio

La métrica Tasa de éxito de Query/Execute >= 99.5% mide la frecuencia con la que se cumplen correctamente los comandos de los usuarios, lo que ayuda a evitar respuestas del Asistente como "No puedo acceder al dispositivo" o confirmar de forma incorrecta un comando que no se cumplió.

¿Qué define un "éxito"?

Una transacción se marca como exitosa si la plataforma de Google Home recibe una respuesta válida que indica que se cumplió la acción deseada o que se recuperó el estado solicitado.

Las respuestas que incluyen excepciones que no generan un bloqueo (por ejemplo, un estado SUCCESS acompañado de una excepción lowBattery) se consideran transacciones exitosas. El comando llegó al dispositivo y el intent se satisfizo a pesar de la advertencia.

¿Qué define una "falla"?

Los errores que se encuentran en Códigos de error comunes de la plataforma y que están marcados como Acción del socio se consideran "fallas" cuando se calculan las tasas de éxito de QUERY y EXECUTE. Además, los errores que se encuentran en Errores y excepciones también son "fallas", con las siguientes excepciones:

La métrica Latencia de Query/Execute (p90) <= 1000 ms mide el tiempo de espera de la acción solicitada y ayuda a garantizar que los usuarios no tengan que esperar demasiado tiempo, por ejemplo, unos segundos para que se apague la luz.

Métricas de latencia

La latencia es un indicador fundamental de la capacidad de respuesta de tu integración para el usuario final. El panel hace un seguimiento de la latencia del percentil 90 (P90), que representa la experiencia de tus usuarios "más lentos" (por ejemplo, un P90 de 800 ms significa que el 90% de las solicitudes se reconocen en 800 ms o menos).

Google mide la latencia de manera diferente para las verificaciones de estado en comparación con los comandos del dispositivo para garantizar la exactitud técnica.

1. Latencia de QUERY (interrogativa)

Mide el tiempo de ida y vuelta de Cloud-to-cloud cuando Google solicita el estado actual de un dispositivo.

• Inicio: Google envía una solicitud action.devices.QUERY a tu URL de entrega.
• Ventana de medición: Es el tiempo que tarda tu nube en recibir, procesar y transmitir la respuesta HTTP completa a Google.
• Fin: Google recibe y reconoce la carga útil de la respuesta final de tu servicio.

2. Latencia de EXECUTE (acción)

Mide el tiempo de reconocimiento del comando cuando Google envía una solicitud de control a un dispositivo.

• Inicio: Google envía una solicitud action.devices.EXECUTE a tu URL de entrega.
• Ventana de medición: Es el tiempo que tarda tu nube en recibir el comando y mostrar una respuesta de reconocimiento.
• Fin: Google recibe la respuesta de estado SUCCESS, PENDING o OFFLINE.
• Alcance técnico: Esta métrica mide el tiempo de "Response Ack" entre la nube de Google y tu nube. No mide el tiempo que tarda el hardware físico (por ejemplo, una bombilla) en completar el cambio de estado físico, ya que, a menudo, implica una latencia de red en malla local fuera de la ruta de acceso de nube a nube.

Opciones de reducción de latencia

Recomendaciones de arquitectura para el enrutamiento geográfico

Si la implementación de IP de Anycast no es factible, te recomendamos las siguientes alternativas rentables para garantizar que los usuarios reciban servicio del centro de datos regional más cercano.

1. Balanceo de cargas global (GLB)

   En lugar del enrutamiento estático, usa un balanceador de cargas de aplicaciones global (disponible en la mayoría de los proveedores de servicios en la nube principales).

   • Cómo funciona: Configuras un solo punto de entrada global (URL) que se encuentra en el perímetro de la red. El balanceador de cargas detecta automáticamente el origen geográfico de la solicitud de los clústeres de entrega de Google y enruta el tráfico a tu backend regional en buen estado más cercano.

   • Beneficio: Esto proporciona el rendimiento de Anycast con una complejidad y un costo de configuración significativamente más bajos.

2. DNS con reconocimiento de ubicación geográfica (GeoDNS)

   • Cómo funciona: Configura tu proveedor de DNS para que resuelva tu URL de entrega en diferentes direcciones IP según la ubicación geográfica de la consulta de DNS.

   • Implementación: Asegúrate de que tu proveedor de DNS esté optimizado para los puntos de salida de Google. Cuando los servicios de entrega regionales de Google (por ejemplo, en EE.UU., la UE o Asia) resuelvan tu dominio, recibirán la dirección IP del centro de datos en esa región específica.

Estrategias de optimización en la capa de aplicación

Además del enrutamiento a nivel de la infraestructura, puedes implementar las siguientes estrategias en la capa de aplicación para reducir la latencia en el procesamiento de solicitudes.

1. El método de proxy "Trampoline"

   Si debes mantener un centro de datos principal, usa servidores proxy regionales ligeros (Trampolines) para controlar el protocolo de enlace inicial.

   1. Google accede a tu URL global.

   2. Un proxy regional (por ejemplo, una función ligera de Nginx o Lambda) recibe la solicitud.

   3. El proxy reenvía la carga útil a través de tu red troncal interna de alta velocidad a la base de datos principal.

   Beneficio: Esto reduce el tiempo de "protocolo de enlace TCP", que suele ser el factor que más contribuye a la latencia de las solicitudes de larga distancia.

2. Sugerencias de región del token de acceso

   Durante el proceso de vinculación de cuentas (OAuth), tu sistema puede identificar la región de origen del usuario.

   Implementación: Codifica un identificador de región en el access_token emitido a Google. Cuando Google envía una solicitud de entrega, tu puerta de enlace puede inspeccionar el token de inmediato y enrutar la solicitud al clúster regional correcto sin necesidad de buscar en la base de datos.

Estado del sistema: Métricas del socio a Google

Mantener una tasa de éxito >= 99.5% ayuda a garantizar que los estados del dispositivo sean correctos en Google Home, que los dispositivos se agreguen y quiten, que se activen las automatizaciones y que los eventos del historial aparezcan en la pestaña Actividad de Google Home app (GHA).

La tasa de éxito se calcula en función de los códigos de respuesta HTTP que muestra Google cuando tu nube envía actualizaciones de estado. Para garantizar que los socios no sean penalizados por problemas de infraestructura del lado de Google, la métrica excluye los errores internos de Google del recuento de fallas. Las llamadas a la API incluidas en el cálculo se encuentran en la referencia de la API de HomeGraph.

¿Qué define un "éxito"?

2xx (éxito): Home Graph recibió y procesó correctamente la actualización de estado.

¿Qué define una "falla"?

4xx (error del socio) representan fallas e indican un problema con la solicitud enviada desde tu nube. Entre los códigos comunes, se incluyen los siguientes:

400 Bad Request

Causa: El servidor no pudo procesar la solicitud debido a una sintaxis no válida. Entre las causas comunes, se incluyen el uso de JSON con formato incorrecto o el uso de valores nulos en lugar de "" para un valor de cadena.

Solución: Asegúrate de que el cuerpo de la solicitud sea un JSON válido (sin estructura con formato incorrecto ni valores nulos para los campos de cadena) y verifica que agentUserId coincida con el valor de la respuesta SYNC.

404 No encontrado

Causa: No se encontró deviceId o agentUserId en HomeGraph (aún no se sincronizó, ya se desvinculó o no coincide el ID).

Solución:

1. Asegúrate de que el agentUserId coincida con el valor proporcionado en tu respuesta SYNC.
2. Usa la API de Home Graph SYNC para determinar si el error 404 Not Found se debe a la falta de un dispositivo o un usuario en HomeGraph.
3. Asegúrate de activar requestSync después de agregar, quitar, cambiar el nombre o actualizar un dispositivo o una cuenta para garantizar que el estado se mantenga actualizado.
4. Controla correctamente los intents DISCONNECT para dejar de informar dispositivos inactivos. Después de recibir el intent DISCONNECT, tu servicio en la nube debe dejar de publicar cambios en Google con Request Sync y Report State.

429 Resource Exhausted

Causa: Tu integración excedió la cuota asignada.

Solución: Consulta las instrucciones en la sección "Paso 2a: Depura problemas de cuota" del panel para administrar la cuota. También puedes consultar Cuotas y límites de casa inteligente para obtener más información.

Estado del dispositivo: Exactitud del estado

Cumplir o superar una exactitud del estado >= 99.5% ayuda a garantizar que los usuarios vean resultados correctos cuando consultan los estados del dispositivo o usan funciones potenciadas por IA como Preguntarle a Home. Si la exactitud del estado es baja, es posible que las automatizaciones no se activen y que las entradas del historial no aparezcan en la pestaña Actividad de GHAen el momento adecuado. Para obtener más información, consulta Report State.

El panel de calidad hace un seguimiento de esto por hora con dos métricas distintas: Exactitud general y la combinación de tipo/rasgo más baja.

1. Componentes de exactitud

La métrica se deriva de "muestras" en las que Google puede verificar el estado informado en función de un resultado de intent conocido.

2. Métricas del panel (cálculo por hora)

El panel calcula la exactitud en función de un intervalo de 1 hora. Si una hora tiene menos de 100 muestras totales (S_Total < 100), la exactitud para esa hora se establece en N/A.

Vista 1: Exactitud general (promedio global)

Representa la exactitud total de tu integración en todos los tipos y rasgos de dispositivos combinados. Proporciona un promedio ponderado del estado de todo tu ecosistema.

• Cálculo: Exactitud total del estado en todos los dispositivos / Total del estado en todos los dispositivos.

Vista 2: Combinación de tipo/rasgo más baja

Identifica la categoría específica menos confiable de tu integración. Evita que los dispositivos de alto volumen que son de alta calidad oculten los dispositivos de bajo volumen que son de baja calidad. Por ejemplo, si tienes un gran volumen de luces con una exactitud del estado superior al 99.5%, pero un volumen bajo de interruptores con una exactitud del estado baja, esto destaca la mejora necesaria en los interruptores que pueden perderse en un valor promedio.

• Cálculo: Mínimo de la exactitud del estado / Total del estado para todas las combinaciones de rasgo/dispositivo.

3. Cómo mejorar el estado del dispositivo y la exactitud del estado

Las discrepancias se producen cuando el estado almacenado en Home Graph no coincide con los resultados de una QUERY en tiempo real.

Errores de "Missing Field"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

Causa: Con el error DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD o DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, el conjunto de campos de carga útil difiere entre tu respuesta QUERY y tu solicitud Report State para el mismo dispositivo.

Solución: Asegúrate de que la estructura de datos sea idéntica en ambas rutas de acceso. Si se incluye un rasgo en SYNC, sus campos correspondientes deben estar presentes y ser coherentes en los informes proactivos y las consultas reactivas.

Errores de "Inaccurate"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

Causa: Para el error DETAILED_ACCURACY_RESULT_INACCURATE, hay una discrepancia entre el valor que se muestra en la respuesta QUERY y el último valor de Report State.

Solución: Asegúrate de que Report State se active cada vez que cambie el estado de un dispositivo y que Report State y QUERY siempre proporcionen los mismos valores actualizados y todos los campos obligatorios para mantener la coherencia de los datos.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

Causa: Con el error DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, el socio ejecutó el comando correctamente, pero no informó el estado actualizado del dispositivo a Google.

Solución: Envía siempre una actualización de Report State después de la ejecución del comando para que Home Graph reciba el nuevo estado del dispositivo.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

Causa: Para el error DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, no se recibió ningún Report State para este dispositivo (el estado está vacío y la marca de tiempo informada está en la época), a pesar de que los resultados de QUERY proporcionan el estado actual. Esto indica que las actualizaciones de estado no se activan, no llegan a HomeGraph o el dispositivo no informa correctamente las transiciones en su conectividad o estado operativo.

Solución: Asegúrate de que Report State se active y se envíe correctamente para todos los cambios de estado. Verifica que la lógica de backend controle correctamente las actualizaciones de estado, confirme el éxito de la entrega a Google HomeGraph y garantice que el dispositivo sincronice constantemente su estado para mantener la exactitud de la interfaz de usuario y el motor de automatización.