Google Home Vitals (облако)

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

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

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

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

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

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

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

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

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

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

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

Что считается успехом?

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

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

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

Ошибки, перечисленные в статье Распространенные коды ошибок платформы и помеченные как Partner Actionable, считаются сбоями при расчете доли успешных запросов QUERY, EXECUTE и SYNC. Кроме того, к ошибкам относятся проблемы, перечисленные в разделе Ошибки и исключения, за следующими исключениями:

Паритет состояния ответа на выполнение

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

Показатель Задержка запроса/выполнения (p90) <= 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.
• Техническая область. Этот показатель измеряет время подтверждения ответа между облаком Google и вашим облаком. При этом не учитывается время, которое требуется физическому оборудованию (например, лампочке), чтобы изменить физическое состояние, поскольку это часто связано с задержкой в локальной ячеистой сети за пределами пути между облаками.

Разбивка задержки EXECUTE/QUERY по времени

При анализе временных меток для задержки 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.

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

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

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

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

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

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

   • Преимущество. Вы получаете эффективность Anycast при значительно меньшей сложности настройки и стоимости.

2. DNS с учетом местоположения (GeoDNS)

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

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

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

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

1. Метод прокси-сервера Trampoline

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

   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 отсутствием устройства или пользователя в HomeGraph.
3. Чтобы поддерживать актуальность состояния, обязательно активируйте requestSync после добавления, удаления, переименования или обновления устройства или аккаунта.
4. Правильно обрабатывайте интенты DISCONNECT, чтобы не получать отчеты об устаревших устройствах. После получения интента DISCONNECT ваш облачный сервис должен прекратить публикацию изменений в Google с помощью Request Sync и Report State.

429 Resource Exhausted

Причина. Превышена квота на интеграцию.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Решение. Убедитесь, что 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 об обновленном состоянии устройства.

Решение. Всегда отправляйте обновление Report State после выполнения команды, чтобы 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, либо устройство не может успешно сообщить об изменениях в своем подключении или рабочем состоянии.

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