Google Home Vitals (Cloud)

Этот набор панелей мониторинга и оповещений помогает вам заблаговременно поддерживать высококачественную интеграцию с экосистемой Google Home. Google стремится поддерживать партнеров в развитии высококачественной экосистемы для всех клиентов.

Панель управления состоит из трех разделов, каждый из которых охватывает ключевой аспект, влияющий на качество общей интеграции.

1. Google to Partner Metrics — измеряет качество запросов от Google к вашей облачной серверной части.

2. Состояние системы — партнер Google Metrics — измеряет качество вызовов из вашей системы в Google.

3. Состояние устройства — Точность состояния — Измеряет точность состояний, хранящихся в системах Google, которые используются для обработки запросов пользователей.

Когда показатели не достигают целевых значений, они выделяются красным цветом, указывая на проблему, которая может повлиять на пользовательский опыт. Ниже представлена ​​подробная информация о каждом целевом показателе и о том, почему он важен для ваших пользователей.

Если следующая кнопка не переводит вас непосредственно на панель управления, вы можете перейти к ней, выбрав страницу «Обзор» , затем «Панели управления» и, из списка « Мои панели управления», выбрав «Панель управления Google Home Vitals (Cloud)» , чтобы просмотреть свою панель управления.

Перейдите на панель управления.

Показатели Google для партнеров

Показатель успешности запросов/выполнения >= 99,5% измеряет, как часто команды пользователей выполняются правильно, что помогает избежать ответов Ассистента типа «Я не могу связаться с устройством» или неправильного подтверждения команды, которая еще не была выполнена.

Что определяет "успех"?

Транзакция считается успешной, если платформа Google Home получает действительный ответ, указывающий на то, что запланированное действие было выполнено или запрошенное состояние было получено.

Ответы, содержащие неблокирующие исключения (например, статус SUCCESS , сопровождаемый исключением lowBattery ), считаются успешными транзакциями. Команда достигла устройства, и намерение было удовлетворено, несмотря на предупреждение.

Что определяет понятие «неудача»?

Ошибки, обнаруженные в кодах ошибок общей платформы и помеченные как требующие вмешательства партнера , считаются «сбоями» при расчете показателей успешности запросов и выполнения. Кроме того, ошибки, обнаруженные в разделах «Ошибки» и «Исключения », также считаются «сбоями», за исключением следующих случаев:

Показатель задержки запроса/выполнения (стр. 90) <= 1000 мс измеряет время ожидания запрошенного действия и помогает гарантировать, что пользователям не придется слишком долго ждать, например, несколько секунд, пока выключится свет.

Метрики задержки

Задержка — это критически важный показатель того, насколько быстро ваша интеграция реагирует на действия конечного пользователя. Панель мониторинга отслеживает задержку 90-го процентиля (P90), которая отражает опыт ваших «самых медленных» пользователей (например, P90 800 мс означает, что 90% запросов подтверждаются за 800 мс или меньше).

Для обеспечения технической точности Google измеряет задержку по-разному при проверке состояния и при выполнении команд устройству.

1. Задержка запроса (вопросительный)

Этот параметр измеряет время обмена данными Cloud-to-cloud , когда Google запрашивает текущее состояние устройства.

• Начало: Google отправляет запрос action.devices.QUERY на ваш URL-адрес выполнения.
• Окно измерения: время, необходимое вашему облаку для получения, обработки и передачи полного HTTP-ответа обратно в Google.
• В заключение: Google получает и подтверждает получение окончательного ответа от вашего сервиса.

2. ВЫПОЛНИТЬ Задержка (Действие)

Этот параметр измеряет время подтверждения команды, когда Google отправляет запрос на управление устройству.

• Начало: Google отправляет запрос action.devices.EXECUTE на ваш URL-адрес выполнения.
• Окно измерения: время, необходимое вашему облаку для получения команды и отправки подтверждающего ответа.
• В итоге Google получает ответ со статусом SUCCESS , PENDING или OFFLINE .
• Техническая область применения: Этот показатель измеряет время подтверждения ответа (Response Ack) между облаком Google и вашим облаком. Он не измеряет время, необходимое физическому оборудованию (например, лампочке) для завершения изменения физического состояния, поскольку это часто связано с задержкой в ​​локальной сети за пределами пути между облаками.

варианты снижения задержки

Архитектурные рекомендации по геомаршрутизации

Если внедрение Anycast IP невозможно, мы рекомендуем следующие экономически эффективные альтернативы, чтобы обеспечить обслуживание пользователей ближайшим региональным центром обработки данных.

1. Глобальная балансировка нагрузки (GLB)

   Вместо статической маршрутизации используйте глобальный балансировщик нагрузки приложений (доступен у большинства крупных облачных провайдеров).

   • Как это работает: Вы настраиваете единую глобальную точку входа (URL), расположенную на границе сети. Балансировщик нагрузки автоматически определяет географическое происхождение запроса из кластеров обработки запросов Google и направляет трафик к ближайшему к вам региональному работоспособному бэкэнду.

   • Преимущество: Это обеспечивает производительность Anycast при значительно меньшей сложности и стоимости настройки.

2. DNS с учетом геолокации (GeoDNS)

   • Как это работает: Настройте своего DNS-провайдера так, чтобы он разрешал ваш URL-адрес выполнения запроса на разные IP-адреса в зависимости от географического местоположения DNS-запроса.

   • Реализация: Убедитесь, что ваш DNS-провайдер оптимизирован для исходящих точек Google. Когда региональные службы обработки запросов Google (например, в США, ЕС или Азии) будут разрешать ваш домен, они получат IP-адрес центра обработки данных в этом конкретном регионе.

Стратегии оптимизации на уровне приложения

Помимо маршрутизации на уровне инфраструктуры, для уменьшения задержки при обработке запросов можно реализовать следующие стратегии на уровне приложений.

1. Метод "батута" как заменитель

   Если вам необходимо поддерживать основной центр обработки данных, используйте региональные легковесные прокси-серверы (Trampolines) для обработки первоначального подтверждения соединения.

   1. Google обращается к вашему глобальному URL-адресу.

   2. Запрос принимается региональным прокси-сервером (например, легковесной функцией Nginx или Lambda).

   3. Прокси-сервер пересылает полезную нагрузку по вашей внутренней высокоскоростной магистрали в основную базу данных.

   Преимущество: Это сокращает время "TCP-рукопожатия", которое часто является основным фактором, влияющим на задержку при запросах на большие расстояния.

2. Подсказки по регионам для получения токена доступа

   В процессе привязки учетной записи (OAuth) ваша система может определить домашний регион пользователя.

   Реализация: В код access_token выданный Google, необходимо внести идентификатор региона. Когда Google отправляет запрос на выполнение, ваш шлюз может немедленно проверить токен и направить запрос в нужный региональный кластер без необходимости обращения к базе данных.

Состояние системы — партнер Google по метрикам.

Поддержание уровня успешности >= 99,5% помогает гарантировать корректность состояния устройств в Google Home, добавление и удаление устройств, запуск автоматизаций и отображение событий истории на вкладке «Действия» в Google Home app (GHA) .

Показатель успешности рассчитывается на основе кодов HTTP-ответа, возвращаемых Google при отправке обновлений состояния вашего облака. Чтобы гарантировать, что партнеры не будут подвергаться санкциям из-за проблем с инфраструктурой Google, этот показатель исключает внутренние ошибки Google из общего числа сбоев. Список вызовов API, включенных в расчет, можно найти в справочнике API HomeGraph .

Что определяет "успех"?

2xx (Успех): Обновление состояния было успешно получено и обработано Home Graph.

Что определяет понятие «неудача»?

Коды 4xx (Partner Error) означают сбои и указывают на проблему с запросом, отправленным из вашего облака. К распространенным кодам относятся:

400 Неверный запрос

Причина: Сервер не смог обработать запрос из-за недопустимого синтаксиса. Распространенные причины включают некорректный JSON или использование значения null вместо "" для строкового значения.

Решение: Убедитесь, что тело запроса представляет собой корректный JSON (без некорректной структуры или нулевых значений в строковых полях), и проверьте, что agentUserId совпадает со значением из ответа SYNC .

404 Не найдено

Причина: deviceId или agentUserId не найдены в HomeGraph (еще не синхронизированы, уже отвязаны или несоответствие идентификаторов).

Решение:

1. Убедитесь, что agentUserId совпадает со значением, указанным в ответе SYNC .
2. Используйте API Home Graph SYNC , чтобы определить, вызвана ли ошибка 404 Not Found отсутствием устройства или пользователя в HomeGraph.
3. Обязательно запускайте requestSync после добавления, удаления, переименования или обновления устройства или учетной записи, чтобы обеспечить актуальность состояния.
4. Надлежащим образом обрабатывайте намерения DISCONNECT , чтобы прекратить отправку отчетов об устаревших устройствах. После получения намерения DISCONNECT ваш облачный сервис должен прекратить публикацию изменений в Google с помощью Request Sync and Report State .

429 Ресурс исчерпан

Причина: Ваша интеграция превысила выделенную квоту.

Решение: Инструкции по управлению квотами см. в разделе «Шаг 2a: Отладка проблем с квотами» на панели управления. Для получения дополнительной информации также обратитесь к разделу «Квоты и ограничения для умного дома» .

Состояние устройства — точность определения состояния

Достижение или превышение точности определения состояния >= 99,5% помогает гарантировать, что пользователи будут видеть правильные результаты при просмотре состояний устройства или использовании функций ИИ, таких как «Спроси дом». Если точность определения состояния низкая, автоматизация может не срабатывать, а записи истории могут не отображаться на вкладке «Действия» в GHA в нужное время. Для получения дополнительной информации см. «Сообщить о состоянии» . Обратите внимание: целевой показатель точности определения состояния должен быть достигнут для ВСЕХ поддерживаемых характеристик.

1. Компоненты точности

Этот показатель рассчитывается на основе «выборок», позволяющих Google проверить сообщаемое состояние на соответствие известному результату намерения. Для обеспечения технической точности оценка достоверности проводится по двум различным направлениям:

• Точность на основе запросов: проверяется, когда пользователь или система активно запрашивают текущее состояние устройства.
• Точность, основанная на выполнении команды: проверяется путем оценки состояния устройства, сообщаемого после запроса управления.

2. Показатели на панели управления (почасовой расчет)

Панель мониторинга рассчитывает точность на основе 1-часового интервала . Для обеспечения статистической достоверности и во избежание снижения эффективности интеграций при низком уровне сигнала Google устанавливает минимальный пороговый объем трафика . Если для определенной комбинации признака и устройства за скользящий 5-дневный период получено менее 100 выборок, ее точность считается статистически незначимой и устанавливается значение N/A .

Когда за час достигается достаточный объем выборки по обоим каналам, базовая почасовая точность для конкретного штата вычисляется как среднее значение двух независимых процентных показателей:

Точность состояния в час = (Точность запроса % + Точность выполнения %) / 2

Каждый из этих путей определяется следующим образом:

• Точность запроса в процентах = (Количество точных запросов за час) / (Общее количество запросов за час)
• Точность выполнения (%) = (Количество точных выборок выполнения за час) / (Общее количество выборок выполнения за час)

Показатель точности определения признака (рассчитывается для каждого признака) = Сумма (количество точных образцов по запросу + количество точных образцов по результатам выполнения) / Сумма (общее количество образцов по запросу + общее количество образцов по результатам выполнения)

Поскольку оценка качества определяет строгие минимальные показатели производительности во всей вашей экосистеме, каждый поддерживаемый и подходящий признак должен индивидуально соответствовать целевому показателю точности состояния >= 99,5% (это не среднее значение по всем признакам).

Такой подход предотвращает маскировку проблем с точностью на устройствах с меньшим объемом трафика устройствами, использующими устройства с большим объемом данных. Партнеры, обеспокоенные тем, что недоиспользуемые характеристики снижают их оценку, могут быть уверены, что редко используемая характеристика автоматически защищается проверкой минимального объема трафика и не будет учитываться при расчете оценки по типу и характеристике с наименьшим значением, если она не соответствует требуемому пороговому значению выборки.

3. Повышение точности определения состояния и работоспособности устройства.

Расхождения возникают, когда состояние, хранящееся в Home Graph, не соответствует результатам запроса в реальном времени.

Ошибки типа «Отсутствующее поле»

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"
  }
  

Причина: При возникновении ошибок DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD или DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD набор полей полезной нагрузки различается между ответом на запрос QUERY и запросом Report State для одного и того же устройства.

Решение: Убедитесь, что структура данных идентична в обоих путях. Если признак включен в SYNC, соответствующие ему поля должны присутствовать и быть согласованными как в проактивных отчетах, так и в реактивных запросах.

«Неточные» ошибки

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"
  }
  

Причина: Ошибка DETAILED_ACCURACY_RESULT_INACCURATE возникает из-за несоответствия между значением, возвращенным в ответе на запрос, и последним значением состояния отчета.

Решение: Убедитесь, что отчет о состоянии устройства запускается при каждом изменении статуса устройства, и что отчет о состоянии устройства и запрос всегда предоставляют одни и те же актуальные значения и все необходимые поля для обеспечения согласованности данных.

"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"
   }
  

Причина: При возникновении ошибки DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE партнер успешно выполнил команду, но не передал обновленное состояние устройства обратно в Google.

Решение: Всегда отправляйте обновление состояния отчета после выполнения команды, чтобы Home Graph получал новое состояние устройства.

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"
   }
  

Причина: Ошибка DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED связана с тем, что для данного устройства не получен отчет о состоянии (состояние пустое, а указанная метка времени соответствует эпохе), несмотря на то, что результаты запроса предоставляют текущий статус. Это указывает на то, что обновления состояния либо не запускаются, либо не достигают HomeGraph, либо устройство не сообщает о переходах в своем состоянии подключения или работоспособности.

Решение: Убедитесь, что отчет о состоянии запускается и успешно отправляется при всех изменениях состояния. Проверьте, правильно ли логика бэкэнда обрабатывает обновления статуса, подтверждает ли успешную доставку в Google HomeGraph и обеспечивает ли постоянную синхронизацию состояния устройства для поддержания точности пользовательского интерфейса и механизма автоматизации.