Связь между облаками имеет значение
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 . Для получения информации по устранению неполадок обратитесь к следующей таблице. Полный список кодов ошибок см. в разделе «Ошибки и исключения» .
| Код ошибки | Описание | Действия партнера |
|---|---|---|
ACTION_NOT_AVAILABLE | Данная команда недействительна для текущего состояния устройства (например, "Установить температуру", когда устройство выключено). Проверьте характеристики устройства и логику текущего состояния в процессе выполнения заказа. | Да |
AGENT_ISSUE | Возникла общая проблема с облачным агентом партнера. Проверьте журналы выполнения на наличие необработанных исключений или сбоев. | Да |
AGENT_UNAVAILABLE_ERROR | Google не смог получить доступ к URL-адресу партнера для выполнения заказов. Убедитесь, что ваш сервер подключен к сети, брандмауэр не блокирует доступ Google и URL-адрес указан правильно. | Да |
APP_LAUNCH_FAILED | Не удалось запустить стороннее приложение на целевом устройстве. Проверьте идентификатор приложения (appId) и убедитесь, что приложение поддерживается целевым оборудованием. | Да |
AUTH_EXPIRED | Срок действия токена доступа OAuth истек, и его невозможно обновить. Проверьте ротацию токенов обновления и убедитесь, что пользователь не отозвал доступ. | Да |
BACKEND_FAILURE_URL_TIMEOUT | Запрос Google к вашему сервису завершился по истечении времени ожидания. Убедитесь, что ваша служба подключена к сети, принимает соединения и не перегружена. Кроме того, убедитесь, что целевое устройство включено, подключено к сети и синхронизировано. | |
BACKEND_FAILURE_URL_UNREACHABLE | Компания Google получила от вашего сервиса код ошибки HTTP 5xx. Используйте requestId в Google Cloud Logging, чтобы проверить журналы работы вашей системы умного дома. | |
CHANNEL_SWITCH_FAILED | Устройство не смогло переключиться на запрошенный медиаканал. Проверьте названия/номера каналов и статус подписки пользователя. | Да |
CHARGER_ISSUE | Устройство сообщает о проблеме с аппаратной частью системы зарядки. Партнеру следует изучить данные телеметрии на аппаратном уровне и состояние батареи. | Да |
CHECK_PARTNER_APP | Для устранения ошибки пользователю необходимо открыть приложение партнера. Этот код следует использовать для обработки ошибок, требующих сложного взаимодействия с пользовательским интерфейсом (например, при обновлении прошивки). | Да |
COMMAND_FAILED | Произошла общая ошибка во время выполнения команды. Проверьте журналы выполнения запросов на наличие конкретного requestId , чтобы найти первопричину проблемы. | Да |
COMMAND_INSERT_FAILED | Компания Google не смогла поставить команду в очередь или обработать её для устройства. Изучите производительность записи в базу данных или внутреннюю логику постановки команд в очередь. | Да |
DEVICE_NOT_FOUND | Идентификатор устройства в запросе отсутствует на стороне партнера. Убедитесь, что ваше облако запускает requestSync , когда пользователь добавляет или удаляет устройства. | Да |
ERROR_STATUS | В ответе был указан неспецифический статус «ОШИБКА» без кода. Для улучшения качества речи пользователей и качества данных на панели управления всегда указывайте конкретный код errorCode . | Да |
EXECUTION_BACKEND_FAILURE_URL_ERROR | Компания Google получила от вас ошибку HTTP 4xx (отличную от 401) при выполнении заказа. Проверьте журналы вашего веб-сервера на наличие ответов 403, 404 или 400. | Да |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED | URL-адрес, используемый для выполнения запроса, блокируется файлом robots.txt или фильтрами безопасности. Убедитесь, что ваша конечная точка обработки заказов доступна для поисковых роботов/сервисов Google. | Да |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE | Компания Google получила от вашей службы выполнения заказов ошибку HTTP 5xx. Проведите расследование причин сбоев сервера, превышения времени ожидания или ошибок шлюза 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_READ_ONLY_MODE_FOR_3P | Интеграция находится в режиме только для чтения на стороне партнера. Проверьте, не заблокирована ли учетная запись пользователя или не находится ли она в режиме технического обслуживания "только для просмотра". | Да |
EXECUTION_GAL_UNLINKED_BY_3P | Учетная запись была автоматически отвязана сторонним сервисом. Выясните причину отключения пользователя (например, сброс настроек безопасности). | Да |
EXECUTION_INVALID_JSON | JSON-ответ не удалось обработать Google. Проверьте свой ответ на наличие синтаксических ошибок, пропущенных скобок или недопустимых символов. | Да |
FAULTY_BATTERY | Аппаратное обеспечение устройства сообщает о неисправности или разрядке батареи. Проинструктируйте пользователя, использующего синтез речи или приложение, заменить физическую батарею. | Да |
FUNCTION_NOT_SUPPORTED | Запрошенный режим или функция не поддерживаются устройством. Убедитесь, что ответ SYNC точно отражает возможности устройства. | Да |
HARD_ERROR | Непрерывный сбой, который не устранится без ручного вмешательства. Используйте это в случае необратимых сбоев оборудования или невосстановимого состояния учетной записи. | Да |
INVALID_AUTH_TOKEN | Компания Google получила от вашего сервиса код ошибки HTTP 401. Срок действия токена доступа не истёк, но ваш сервис его аннулировал. Используйте requestId в Google Cloud Logging, чтобы проверить журналы работы вашей службы умного дома. | |
INVALID_JSON | Структура ответа некорректна (например, отсутствуют обязательные поля). Проверьте свой ответ на соответствие JSON-схемам намерений . | Да |
LOCK_FAILURE | «Умный» замок не смог перейти в запрошенное состояние. Проверьте, нет ли физических заклиниваний, низкого напряжения или неисправностей двигателя в механизме замка. | Да |
MALFORMED_JSON | Структура JSON нарушена (например, незакрытые строки или объекты). Убедитесь, что в вашей системе обработки запросов используется стандартная библиотека JSON для сериализации ответов. | Да |
MISSING_STATE | В ответе на запрос не содержалось запрошенное состояние устройства. Убедитесь, что все характеристики, определенные в SYNC , учитываются в каждом ответе QUERY . | Да |
NETWORK_PROFILE_NOT_RECOGNIZED | Запрошенный сетевой профиль неизвестен устройству. Убедитесь, что строка с именем профиля соответствует поддерживаемым профилям в ответе SYNC . | Да |
NOT_IMPLEMENTED | Запрошенное намерение или свойство не было реализовано партнером. В ответ на запрос SYNC включайте только те характеристики, которые вы полностью внедрили. | Да |
OAUTH_RECONNECT_CALL_TO_ACTION | Запускает уведомление для пользователя о необходимости повторной привязки его учетной записи. Используйте это, когда сессия пользователя аннулирована и требуется повторная аутентификация OAuth вручную. | Да |
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 | В ответе не были указаны результаты для всех запрошенных команд/устройств. Каждый элемент в массиве commands запроса должен иметь соответствующую запись ответа. | Да |
PARTNER_RESPONSE_MISSING_DEVICE | В ответе не было указано конкретное устройство, запрошенное Google. Убедитесь, что ваш ответ содержит все ID указанные в полезной нагрузке запроса. | Да |
PARTNER_RESPONSE_MISSING_PAYLOAD | В ответе отсутствует обязательное поле payload .Убедитесь, что ваш JSON-объект верхнего уровня содержит ключ payload . | Да |
PARTNER_RESPONSE_NOT_OBJECT | Весь ответ не удалось преобразовать в объект JSON. Проверьте тело HTTP-ответа на наличие символов в конце или содержимого, не относящегося к JSON. | Да |
PROTOCOL_ERROR | Произошла ошибка в базовом протоколе связи. Проверьте заголовки HTTP или проверьте, не удалось ли установить соединение по протоколу SSL/TLS. | Да |
RELINK_REQUIRED | Для продолжения использования интеграции пользователю необходимо повторно привязать свою учетную запись. Убедитесь, что ваш сервер возвращает этот код, если токен обновления окончательно недействителен. | Да |
REQUEST_ID_NOT_FOUND | Google не смог найти внутренний идентификатор отслеживания для запроса. Обычно это внутренняя ошибка платформы; следите за скачками нагрузки и свяжитесь со службой поддержки. | Да |
RESOURCE_UNAVAILABLE | Запрошенный ресурс (устройство или характеристика) недоступен. Проверьте, не находится ли устройство в состоянии "Занято" или не отключено ли оно временно. | Да |
RESPONSE_TIMEOUT | Служба обработки заказов не ответила в течение 9 секунд. Оптимизируйте задержку на стороне бэкэнда; проверьте наличие медленных запросов к базе данных или региональных сетевых задержек. | Да |
RESPONSE_UNAVAILABLE | Ответа от партнера по адресу доставки не получено. Убедитесь, что ваша служба запущена и конечная точка не аварийно завершает работу. | Да |
SCENE_CANNOT_BE_APPLIED | Запрошенная сцена не может быть активирована (например, отсутствуют устройства). Проверьте внутреннее состояние пользовательских сценариев в партнерском облаке. | Да |
STREAM_UNPLAYABLE | Не удалось запустить видеопоток с камеры, или же произошла ошибка. Проверьте сигнализацию WebRTC/HLS и убедитесь в корректности URL-адреса потока. | Да |
TIMEOUT | Произошло общее превышение времени ожидания при обработке намерения. Проверьте журналы на наличие внутренних таймаутов служб между вашим облаком и устройствами. | Да |
TRANSIENT_ERROR | Временная ошибка — это ошибка, которая исправится сама собой. Чаще всего эти ошибки проявляются в виде разрыва соединения с устройством или службой. Также это происходит, если не удаётся установить новые соединения с сервером. | |
UNABLE_TO_LOCATE_DEVICE | Устройство не удалось обнаружить с помощью параметра Locator (например, проверка связи не удалась). Проверьте локальные возможности устройства (Wi-Fi/Bluetooth). | Да |
UNABLE_TO_RING_DEVICE | Устройство удалось подключить, но функция звонка/оповещения не сработала. Проверьте состояние оповещения/динамика и уровни громкости оборудования. | Да |
UNABLE_TO_SILENCE_DEVICE | Устройство не могло отключить активный сигнал оповещения/звонок. Проведите расследование причин сбоев связи между облаком и физическим устройством. | Да |
UNEXPECTED_ERROR_CHECK_DEVICE_APP | Произошла непредвиденная ошибка; пользователю следует проверить партнерское приложение. Используйте это как универсальный способ для обработки ошибок, для которых нет конкретного аналога, поддерживаемого Google. | Да |
UNKNOWN_ERROR | Типичная ошибка, без предоставления дополнительных подробностей. Рекомендуется заменить эти коды на более конкретные, чтобы упростить поиск и устранение неисправностей. | Да |
UNLOCK_FAILURE | «Умный» замок не смог перейти в состояние «Разблокировано». Рассмотрите возможные проблемы: заклинивание оборудования, низкий заряд батареи или неверный ввод PIN-кода. | Да |
Журналы поиска
После того как вы освоите мониторинг интеграций с помощью метрик, следующим шагом станет устранение конкретных ошибок с помощью Cloud Logging . Журнал ошибок представляет собой запись в формате JSON, содержащую поля с полезной информацией, такой как время, код ошибки и подробности об исходном намерении умного дома.
В Google Cloud существует множество систем, которые постоянно отправляют журналы в ваш проект. Вам необходимо писать запросы для фильтрации журналов и поиска нужных. Запросы могут быть основаны на временном диапазоне , ресурсе , уровне серьезности записи или пользовательских параметрах.
Вы можете использовать кнопки запросов для создания собственных фильтров.
Чтобы указать временной диапазон , нажмите выбора временного диапазона и выберите один из предложенных вариантов. Это отфильтрует журналы и отобразит те, которые относятся к выбранному временному диапазону.
Чтобы указать ресурс , щелкните раскрывающийся список «Ресурс» , затем выберите «Проект действий Google Assistant» . Это добавит фильтр в ваш запрос, чтобы отображать журналы, созданные в рамках вашего проекта.
Используйте кнопку «Уровень серьезности» , чтобы отфильтровать сообщения по уровням серьезности: «Экстренная ситуация» , «Информация» , «Отладка» и другим.
В 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 , которое поможет вам эффективно протестировать ваши изменения.
Учебные ресурсы
В этом документе описаны шаги по устранению ошибок в вашем приложении «Умный дом». Вы также можете ознакомиться с нашими учебными материалами, чтобы узнать больше об отладке:
- Отладка интеграции умного дома в Codelab : краткое руководство по отладке интеграции умного дома с облаком.
- Отладка локальной интеграции умного дома : краткое руководство по отладке локальной интеграции.