Google Home Vitals (облако)

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

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

1. Показатели Google для партнеров – позволяют отслеживать состояние вызовов из Google в облачную инфраструктуру партнера.

2. Состояние системы – показатели Партнера Google – позволяет отслеживать состояние звонков из вашей системы в Google.

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

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

Если кнопка ниже не ведет на нужную страницу, перейдите на страницу Обзор, выберите Сводки, а затем в списке Мои сводки выберите Google Home Vitals Dashboard (Cloud).

Открыть панель управления

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

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

Показатель Доля успешных синхронизаций >= 99,5% отражает, как часто запросы на синхронизацию выполняются правильно.Это гарантирует, что устройства, показанные в Google Home, синхронизированы с устройствами, подключенными к вашей облачной инфраструктуре.

Что считается успешным результатом?

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

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

Что считается сбоем?

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

Соответствие статусов выполнения и ответов

При возврате статуса SUCCESS в ответе EXECUTE объект states в полезной нагрузке ответа должен содержать все активные и обновленные поля состояния, определенные выполняемыми вами признаками. Если не указать обязательные поля состояния или вернуть пустой объект states для сложных характеристик, платформа Google Home не сможет обработать результат выполнения и зарегистрирует его как ошибку AGENT_ISSUE или INVALID_RESPONSE, что приведет к снижению доли успешных запросов и выполнения.

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

Показатели задержки

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

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

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

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

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

2. EXECUTE Latency (Действие)

Это время, которое требуется устройству, чтобы подтвердить получение команды от Google.

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

Разбивка временной шкалы задержки выполнения запроса

При анализе временных меток для задержки EXECUTE или QUERY общее время прохождения сигнала можно разбить на следующие последовательные этапы:

Поскольку в этом отчете сравниваются временные метки Google и партнера, серверы партнера должны быть синхронизированы с помощью протокола NTP (Network Time Protocol). Даже небольшое расхождение во времени (50–100 мс) приведет к искажению рассчитанного времени транспортировки (t2 - t1 и t4 - t3) и, возможно, к логически невозможным показателям, например отрицательному времени транспортировки.

[t1] Запрос отправлен (исходящий запрос Google). Google инициирует запрос намерения. Поскольку значение t1 не показывается напрямую, оно рассчитывается приблизительно путем вычитания общей задержки из конечной входящей временной метки.

Передача по сети (t1–t2). Предполагаемое время передачи по сети и время ожидания в очереди до достижения конечной точки выполнения.

[t2] Получен запрос (вход партнера). Точная временная метка, когда запрос поступает в API-шлюз или входной сервер вашей среды.

Обработка партнером (t2–t3). Внутреннее выполнение, маршрутизация и задержка обработки устройства полностью в вашей облачной среде.

[t3] Ответ отправлен (исходящий трафик партнера). Временная метка, когда ваш сервис отправляет ответ на запрос в Google.

Обратный транзит (t3 в t4). Время обратной маршрутизации и подключения к сети, а также время возврата в Google.

[t4] Запрос выполнен (входящий запрос от Google). Google получает и обрабатывает окончательный ответ. Эта временная метка явно записывается в журналы Google Cloud как receiveTimestamp.

Чтобы понять, как эти показатели связаны друг с другом, рассмотрим пример запроса EXECUTE с общей зарегистрированной задержкой (latencyMsec) 1700 мс и Google Cloud receiveTimestamp (t4) 2026-05-25T15:25:00.550Z.

Варианты уменьшения задержки

Рекомендации по архитектуре для геомаршрутизации

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

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, включенные в расчет, можно найти в справочнике по HomeGraph API.

Что считается успешным результатом?

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

Что считается сбоем?

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

400 Bad Request (Недопустимый запрос)

Причина. Сервер не смог обработать запрос из-за неверного синтаксиса. Чаще всего это происходит из-за неправильного формата JSON или использования значения null вместо пустой строки.

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

Ошибка 404: не найдено

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

Решение

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

429 Resource Exhausted

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

Решение. Следуйте инструкциям в разделе "Шаг 2а. Устранение неполадок с квотами" на панели управления квотами. Также рекомендуем ознакомиться с квотами и ограничениями для умного дома.

Состояние устройства – точность

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

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

Показатель рассчитывается на основе "образцов", в которых Google может проверить заявленное состояние на соответствие известному результату намерения. Точность оценивается по двум направлениям:

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

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

На панели управления точность рассчитывается на основе часового интервала. Чтобы обеспечить статистическую достоверность и избежать штрафов для интеграций с низким уровнем шума, Google устанавливает минимальный порог объема трафика. Если для определенного трейта и устройства за последние 5 дней было собрано менее 100 образцов, точность считается статистически незначимой и устанавливается значение Н/Д.

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

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

где каждый путь определяется следующим образом:

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

Оценка точности признака (рассчитывается для каждого признака) = СУММА(Точные образцы запросов + Точные образцы выполнения) / СУММА(Всего образцов запросов + Всего образцов выполнения)

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

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

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

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

Ошибки "Отсутствует поле"

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 значение, возвращенное в ответе на запрос, не совпадает с последним значением состояния отчета.

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

"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 не был получен ReportState для этого устройства (состояние пустое, а временная метка относится к началу эпохи), хотя результаты QUERY содержат текущий статус. Это означает, что обновления состояния не запускаются, не доходят до HomeGraph или устройство не сообщает об изменениях в подключении или рабочем статусе.

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