Google Cloud предоставляет инструменты для отслеживания надежности проектов с помощью Google Cloud Monitoring и отладки проблем с помощью журналов ошибок Google Cloud Logging. Если при выполнении намерения пользователя возникает ошибка, конвейер Google Home Analytics регистрирует ее в ваших показателях и публикует журнал ошибок в журналах вашего проекта.
Устранение неполадок состоит из двух этапов:
- Отслеживайте состояние проектов с помощью показателей умного дома.
- Чтобы разобраться в проблеме, изучите подробные описания ошибок в журналах.
Вы также можете протестировать действие, поделившись им с другими пользователями. Убедитесь, что вы правильно обрабатываете ошибки и исключения.
Ошибки мониторинга
Для доступа к показателям проекта можно использовать Google Cloud Monitoring dashboard. Есть несколько ключевых диаграмм, которые особенно полезны для мониторинга качества и отладки:
- Диаграмма Доля успешных запросов – это первая диаграмма, с которой следует начинать мониторинг надежности проектов. Падение показателей на этой диаграмме может указывать на сбой у части или всей вашей пользовательской базы. Рекомендуем внимательно следить за этой диаграммой после каждого изменения или обновления проекта.
- Диаграмма 95-й процентиль задержки – важный показатель того, как интеграция Cloud-to-cloud работает для ваших пользователей. Резкие колебания на этой диаграмме могут указывать на то, что ваши системы не справляются с запросами. Рекомендуется периодически проверять эту диаграмму, чтобы выявлять непредвиденные изменения.
- Диаграммы Распределение ошибок наиболее полезны при устранении неполадок в интеграциях. Для каждой ошибки, выделенной на диаграмме успешных загрузок, в разбивке ошибок отображается код ошибки. В таблице ниже перечислены ошибки, которые могут быть обнаружены Google Home platform, и способы их устранения.
Распространенные коды ошибок платформы
Ниже приведены распространенные коды ошибок, которые могут появляться в журналах проекта и указывать на проблемы, обнаруженные Google Home platform. Информацию об устранении неполадок вы найдете в таблице ниже. Полный список кодов ошибок приведен в разделе Ошибки и исключения.
| Код ошибки | Описание | Действия партнера |
|---|---|---|
AGENT_ISSUE |
Возникла общая проблема с облачным агентом партнера.
Проверьте, нет ли в журналах выполнения необработанных исключений или сбоев. |
Да |
AGENT_UNAVAILABLE_ERROR |
Google не удалось связаться с URL выполнения партнера.
Убедитесь, что сервер работает, брандмауэр не блокирует Google, а URL указан правильно. |
Да |
COMMAND_FAILED |
При выполнении команды произошла общая ошибка.
Чтобы найти основную причину, проверьте журналы выполнения на наличие requestId.
|
Да |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google получил от вашего выполнения ошибку HTTP 4xx (кроме 401).
Проверьте, нет ли в журналах веб-сервера ответов 403, 404 или 400. |
Да |
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT |
При попытке связаться с вашим сервисом у запроса Google истекло время ожидания.
Убедитесь, что сервис работает, принимает подключения и не перегружен. Кроме того, убедитесь, что целевое устройство включено, подключено к интернету и синхронизировано. |
Да |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
URL выполнения заблокирован файлом robots.txt или фильтрами безопасности.
Убедитесь, что конечная точка выполнения доступна для поисковых роботов и сервисов Google. |
Да |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google получил ошибку HTTP 5xx от вашего сервиса выполнения.
Убедитесь, что URL конечной точки стабилен, указан правильно и общедоступен, а сервис работает. Используйте requestId в Google Cloud Logging, чтобы проверить журналы сервиса умного дома.
Добавьте проверки работоспособности и обработку повторных попыток.
Проверьте, не было ли сбоев сервера, тайм-аутов или ошибок шлюза 502/503.
|
Да |
EXECUTION_BAILOUT_INVALID_RESPONSE |
Ответ JSON был настолько некорректным, что обработка была прервана.
Используйте валидатор JSON, чтобы убедиться, что ответ строго соответствует схемам Intent. |
Да |
EXECUTION_GAL_BAD_3P_RESPONSE |
Не удалось связать аккаунты из-за недопустимого формата в ответе токена.
Убедитесь, что формат ответа сервера OAuth соответствует требованиям Google. |
Да |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
У аккаунта пользователя нет разрешений, необходимых для выполнения этого действия.
Проверьте области действия, запрашиваемые во время OAuth, и убедитесь, что они соответствуют требуемым характеристикам. |
Да |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
Облако партнера указывает, что пользователь отменил связь с аккаунтом.
Убедитесь, что сопоставление agentUserId стабильно и не было удалено.
|
Да |
EXECUTION_GAL_NOT_FOUND |
Токены доступа и обновления пользователя, хранящиеся в Google, недействительны или не могут быть обновлены, что препятствует аутентификации и доступу к партнерскому сервису.
Убедитесь, что токены остаются действительными и синхронизированными, правильно обрабатывайте изменения статуса аккаунта и требуйте от пользователей повторно связать аккаунт, если подтверждено, что токены отозваны. |
|
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
Интеграция доступна в режиме "только для чтения" на стороне партнера.
Проверьте, не заблокирован ли аккаунт пользователя и не находится ли он в режиме обслуживания "Только просмотр". |
Да |
EXECUTION_GAL_UNLINKED_BY_3P |
Связь с аккаунтом была отменена сторонним сервисом.
Выясните, почему пользователь был отключен (например, из-за сброса настроек безопасности). Убедитесь, что сервер OAuth партнера правильно отвечает на запросы refresh_token от Google, чтобы без проблем выпускать новые токены доступа.
|
Да |
EXECUTION_INVALID_JSON |
Google не удалось обработать полезную нагрузку ответа JSON.
Проверьте, нет ли в ответе синтаксических ошибок, пропущенных скобок или недопустимых символов. |
Да |
INVALID_AUTH_TOKEN |
Google получил от вашего сервиса код ошибки HTTP 401.
Срок действия токена доступа не истек, но ваш сервис аннулировал его. Используйте requestId в Google Cloud Logging, чтобы проверить журналы сервиса умного дома.
|
|
INVALID_JSON |
Недопустимая структура ответа (например, отсутствуют обязательные поля).
Проверьте ответ на соответствие схемам JSON для намерений. |
Да |
MALFORMED_JSON |
Структура JSON нарушена (например, не закрыты строки или объекты).
Убедитесь, что для сериализации ответов используется стандартная библиотека JSON. |
Да |
NOT_IMPLEMENTED |
Запрошенное намерение или свойство не реализовано партнером.
Включайте в ответ SYNC только те свойства, которые вы полностью реализовали.
|
Да |
OPEN_AUTH_FAILURE |
Срок действия токена доступа пользователя истек, и Google не может его обновить, или Google получил от вашего сервиса код ошибки HTTP 401.
Если вы видите, что этот код появляется чаще, проверьте, не увеличилось ли также количество ошибок, связанных с интентами умного дома или запросами токенов обновления. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
Возвращенная строка errorCode не входит в список поддерживаемых Google.
Сопоставьте внутренние ошибки с официальным списком ошибок. |
Да |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Поле payload в ответе не является допустимым объектом JSON.
Проверьте корневую структуру ответа на выполнение. |
Да |
PARTNER_RESPONSE_INVALID_STATUS |
Ответ status не был SUCCESS, ERROR или OFFLINE.
Убедитесь, что в ответе для каждого устройства указана действительная строка статуса. |
Да |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
В ответе не было результатов для всех запрошенных команд или устройств.
Проверьте структуру ответа, используя документацию для разработчиков Google Home. Убедитесь, что ответ не усекается и не возвращает пустое тело из-за внутренней ошибки сервера. Каждому элементу в массиве commands запроса должна соответствовать запись в ответе.
|
Да |
PARTNER_RESPONSE_MISSING_DEVICE |
В ответе не указано определенное устройство, запрошенное Google.
Убедитесь, что ответ содержит все значения ID, указанные в полезной нагрузке запроса.
|
Да |
PARTNER_RESPONSE_MISSING_PAYLOAD |
В ответе отсутствует обязательное поле payload.
Убедитесь, что объект JSON верхнего уровня содержит ключ payload.
|
Да |
PARTNER_RESPONSE_NOT_OBJECT |
Не удалось проанализировать весь ответ как объект JSON.
Проверьте, нет ли в теле HTTP-ответа лишних символов или контента, не относящегося к JSON. Убедитесь, что payload.commands[] – это правильный объект JSON с идентификаторами, статусом и необязательными состояниями.
|
Да |
REQUEST_ID_NOT_FOUND |
Google не удалось найти внутренний идентификатор отслеживания для запроса.
Обычно это внутренняя ошибка платформы. Следите за всплесками и обращайтесь в службу поддержки. |
Да |
RESOURCE_UNAVAILABLE |
Запрошенный ресурс (устройство или trait) недоступен.
Проверьте, не занято ли устройство и не отключено ли оно временно. |
Да |
RESPONSE_TIMEOUT |
Сервис выполнения не ответил в течение 9 секунд.
Оптимизируйте задержку на сервере. Проверьте, нет ли медленных запросов к базе данных или задержек в региональной сети. |
Да |
RESPONSE_UNAVAILABLE |
От URL выполнения заказа партнера не получен ответ.
Убедитесь, что сервис работает и конечная точка не дает сбоев. |
Да |
TIMEOUT |
При обработке намерения истекло время ожидания.
Проверьте журналы на наличие ошибок, связанных с превышением времени ожидания ответа от внутреннего сервиса, между облаком и концентраторами устройств. |
Да |
Журналы поиска
Когда вы научитесь отслеживать интеграции с помощью показателей, следующим шагом будет устранение неполадок, связанных с конкретными ошибками, с помощью Cloud Logging. Журнал ошибок – это запись в формате JSON с полями, содержащими полезную информацию, такую как время, код ошибки и сведения об исходном намерении умного дома.
В Google Cloud есть несколько систем, которые постоянно отправляют журналы в ваш проект. Чтобы найти нужные журналы, вам нужно написать запросы для фильтрации. Запросы могут быть основаны на диапазоне дат, ресурсе, серьезности журнала или специальных записях.
Для создания специальных фильтров можно использовать кнопки запросов.
Чтобы указать диапазон дат, нажмите кнопку выбора диапазона дат и выберите один из доступных вариантов. В результате будут показаны только журналы, относящиеся к выбранному интервалу времени.
Чтобы указать ресурс, нажмите на раскрывающийся список Ресурс и выберите Проект действий Google Ассистента. Это добавит фильтр в ваш запрос, чтобы показывать журналы, которые происходят из вашего проекта.
С помощью кнопки Серьезность можно отфильтровать записи по уровню серьезности, например Экстренная ситуация, Информация, Отладка и т. д.
Вы также можете использовать поле Query (Запрос) в Logs Explorer, чтобы вводить собственные записи. Механизм запросов, используемый этим полем, поддерживает как простые запросы, например сопоставление строк, так и более сложные, в том числе со сравнениями (<, >=, !=) и логическими операторами (AND, OR, NOT).
Например, приведенная ниже запись будет возвращать ошибки, возникающие на устройствах типа LIGHT:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
Дополнительные примеры эффективных запросов к журналам можно найти в библиотеке запросов.
Тестирование исправлений
После того как вы выявите ошибки и внесете исправления, рекомендуем тщательно протестировать их с помощью Google Home Test Suite. Мы предоставляем руководство пользователя по использованию Test Suite, в котором подробно описано, как эффективно тестировать изменения.
Учебные ресурсы
В этом документе описаны шаги по устранению неполадок в действии умного дома. Вы также можете ознакомиться с нашими практическими работами, чтобы узнать больше об отладке:
- Практическая работа по отладке умного дома. Краткое руководство по отладке интеграции умного дома с облаком.
- Практическая работа по отладке локального умного дома. Краткое руководство по отладке локальной интеграции умного дома.