refresh_date: 2023-01-06
Google Cloud предоставляет инструменты для отслеживания надежности проектов с помощью Google Cloud Monitoring и устранения неполадок с помощью журналов ошибок Google Cloud Logging. Если при выполнении намерений пользователя происходит сбой, конвейер Google Home Analytics регистрирует его в ваших показателях и публикует журнал ошибок в журналах проекта.
Чтобы устранить ошибки, выполните следующие действия:
- Отслеживайте состояние проектов с помощью показателей умного дома.
- Изучайте подробные описания ошибок в журналах.
Отслеживание ошибок
Вы можете использовать Google Cloud Monitoring dashboards для доступа к показателям проекта. Ниже перечислены основные диаграммы, которые особенно полезны для отслеживания качества и отладки:
- Диаграмма Доля успешных запросов – первая, с которой нужно начинать мониторинг надежности проектов. Снижение показателей на этой диаграмме может указывать на сбой в работе сервиса для части или всех пользователей. Мы рекомендуем внимательно следить за этим графиком после каждого изменения или обновления проекта.
- Диаграммы Разбивка ошибок наиболее полезны при устранении неполадок в интеграциях. Для каждой ошибки, выделенной на диаграмме успешности, в разбивке ошибок показывается код ошибки. В таблице ниже перечислены ошибки, которые может обнаружить 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, чтобы убедиться, что ответ соответствует схемам намерений. |
Да |
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 |
Сервис выполнения не ответил в течение девяти секунд.
Оптимизируйте задержку на стороне сервера. Проверьте, нет ли медленных запросов к базе данных или региональных задержек в сети. |
Да |
RESPONSE_UNAVAILABLE |
От URL выполнения партнера не получен ответ.
Убедитесь, что сервис работает и конечная точка не зависает. |
Да |
TIMEOUT |
При обработке намерения истекло общее время ожидания.
Проверьте журналы на наличие внутренних тайм-аутов сервиса между облаком и концентраторами устройств. |
Да |
Журналы поиска
Когда вы научитесь отслеживать интеграции с помощью показателей, следующим шагом будет устранение неполадок с помощью Cloud Logging. Журнал ошибок – это запись в формате JSON с полями, содержащими полезную информацию, например время, код ошибки и сведения об исходном намерении для умного дома.
В Google Cloud есть несколько систем, которые постоянно отправляют журналы в ваш проект. Вам нужно составлять запросы, чтобы фильтровать журналы и находить нужные. Запросы могут быть основаны на диапазоне времени, ресурсе, серьезности журнала или специальных записях.
Чтобы создать пользовательские фильтры, используйте кнопки запросов.
Чтобы задать временной диапазон, нажмите на кнопку выбора диапазона и выберите один из предложенных вариантов. Это позволит отфильтровать журналы и показать только те, которые относятся к выбранному временному диапазону.
Чтобы указать ресурс, нажмите на раскрывающийся список Ресурс и выберите Проект действий Google Ассистента. В запрос будет добавлен фильтр, чтобы показывать журналы, относящиеся к вашему проекту.
Нажмите кнопку Серьезность, чтобы отфильтровать данные по уровням серьезности журнала, например Критический, Информация, Отладка и т. д.
Вы также можете использовать поле "Запрос" в 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, в котором рассказывается, как эффективно тестировать изменения.
Учебные ресурсы
В этом документе описаны действия, которые помогут устранить ошибки в действии для умного дома. Также рекомендуем ознакомиться с нашими codelabs, чтобы узнать больше об отладке:
- Практическая работа по отладке умного дома: Краткое руководство по отладке интеграции облачных сервисов умного дома.
- Практическая работа по отладке Local Home – краткое руководство по отладке локальной интеграции умного дома.