Устранение ошибок интеграции Matter

обновить_дату: 06.01.2023

Google Cloud предоставляет вам инструменты для мониторинга надежности ваших проектов с помощью Google Cloud Monitoring и устранения проблем с помощью журналов ошибок Google Cloud Logging . Всякий раз, когда при выполнении намерений пользователя происходит сбой, конвейер Google Home Analytics фиксирует этот сбой в ваших метриках и публикует журнал ошибок в журналах вашего проекта.

Чтобы устранить ошибки, выполните два шага:

  1. Контролируйте состояние своих проектов с помощью показателей умного дома.
  2. Исследуйте проблемы, проверив подробные описания ошибок в журналах ошибок.

Мониторинг ошибок

Вы можете использовать Google Cloud Monitoring dashboard для доступа к показателям вашего проекта. Есть несколько ключевых диаграмм, которые особенно полезны для мониторинга качества и отладки:

  • Диаграмма успеха — это первая диаграмма, с которой следует начинать мониторинг надежности ваших проектов. Падения на этой диаграмме могут указывать на сбой в работе части или всей вашей пользовательской базы. Мы рекомендуем внимательно следить за этой диаграммой на предмет любых нарушений после каждого изменения или обновления вашего проекта.
  • Диаграммы разбивки ошибок наиболее полезны при устранении неполадок в интеграции. Для каждой ошибки, выделенной на диаграмме процента успеха, в разбивке ошибок отображается код ошибки. Вы можете увидеть ошибки, отмеченные Google Home platform , и способы их устранения в таблице ниже.

Коды ошибок платформы

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

Код ошибки Описание
BACKEND_FAILURE_URL_ERROR Google получил от вашей службы код ошибки HTTP 4xx, отличный от 401.

Используйте requestId в журнале GCP, чтобы проверить журналы службы умного дома.
BACKEND_FAILURE_URL_TIMEOUT Время ожидания запроса Google истекло при попытке связаться с вашим сервисом.

Убедитесь, что ваша служба подключена к сети, принимает соединения и не превышает пропускную способность. Кроме того, убедитесь, что целевое устройство включено, подключено к сети и синхронизировано.
BACKEND_FAILURE_URL_UNREACHABLE Google получил от вашего сервиса код ошибки HTTP 5xx.

Используйте requestId в журнале GCP, чтобы проверить журналы службы умного дома.
DEVICE_NOT_FOUND Устройство не существует на стороне партнерской службы.

Обычно это указывает на сбой синхронизации данных или состояние гонки.
GAL_BAD_3P_RESPONSE Google не может проанализировать ответ от службы связывания ваших учетных записей из-за недопустимого формата или значений в полезных данных.

Используйте requestId в журнале GCP, чтобы проверить журналы ошибок в службе связывания учетных записей.
GAL_INTERNAL Внутренняя ошибка Google произошла, когда Google попытался получить токен доступа.

Если вы заметили увеличение частоты возникновения этой ошибки в журнале GCP, свяжитесь с нами для получения дополнительной информации.
GAL_INVALID_ARGUMENT Внутренняя ошибка Google произошла, когда Google попытался получить токен доступа.

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

Если вы заметили увеличение частоты возникновения этой ошибки в журнале GCP, свяжитесь с нами для получения дополнительной информации.
GAL_PERMISSION_DENIED Произошла внутренняя ошибка Google, когда совместное использование токенов не разрешено.

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

Это не проблема и никаких действий не требуется.
INVALID_AUTH_TOKEN Google получил от вашего сервиса код ошибки HTTP 401.

Срок действия токена доступа не истек, но ваша служба аннулировала его. Используйте requestId в журнале GCP, чтобы проверить журналы службы умного дома.
INVALID_JSON Ответ JSON невозможно проанализировать или понять.

Проверьте структуру вашего ответа JSON на наличие недопустимого синтаксиса, например несовпадающих скобок, отсутствующих запятых и недопустимых символов.
OPEN_AUTH_FAILURE Срок действия токена доступа пользователя истек, и Google не может его обновить, или Google получил код ошибки HTTP 401 от вашей службы.

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

Если в вашем ответе на запрос указана ошибка, обязательно используйте один из поддерживаемых нами кодов ошибок .
PARTNER_RESPONSE_INVALID_PAYLOAD Поле payload ответа не может быть проанализировано как объект JSON.

Проверьте, имеет ли поле полезных данных в ответе на запрос соответствующие скобки и правильно ли оно структурировано как поле JSON.
PARTNER_RESPONSE_INVALID_STATUS Ответ не указывает на статус или указывает на неверный статус.

Ответы на запросы на выполнение намерения должны указывать статус: SUCCESS, OFFLINE, ERROR, EXCEPTIONS . Дополнительную информацию об обработке ошибок и исключений можно найти.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES В ответе отсутствует одно или несколько намерений, присутствующих в запросе.

Убедитесь, что ваш ответ на выполнение правильно структурирован и что результаты для всех намерений запроса присутствуют в вашем ответе.
PARTNER_RESPONSE_MISSING_DEVICE В ответе отсутствует одно или несколько устройств, представленных в запросе.

Убедитесь, что ваш ответ на выполнение правильно структурирован и что все идентификаторы устройств из запроса присутствуют в вашем ответе.
PARTNER_RESPONSE_MISSING_PAYLOAD Ответ не содержит поля payload .

Обязательно включите поле полезной нагрузки в ответ на запрос. Подробнее о том, как правильно построить ответ на выполнение , можно узнать.
PARTNER_RESPONSE_NOT_OBJECT Ответ невозможно проанализировать как объект JSON.

Проверьте все поля в ответе на запрос на наличие нежелательных символов, несовпадающих скобок или ошибок форматирования. Некоторые символы Юникода могут не поддерживаться. Также убедитесь, что ваш ответ правильно структурирован как объект JSON.
PROTOCOL_ERROR Сбой в обработке запроса.

Используйте requestId в Google Cloud Logging, чтобы проверить журналы службы умного дома.
RESPONSE_TIMEOUT Время ожидания ответа на запрос истекло.

Тайм-аут отправки ответа составляет 9 секунд с момента отправки запроса. Обязательно отправьте ответ в течение этого периода времени.
RESPONSE_UNAVAILABLE Ответ не получен, или в ответе не указано состояние.

Ответы на запросы о выполнении намерений должны быть структурированы в соответствии с документами по «умному дому» и указывать статус.
TRANSIENT_ERROR Временная ошибка — это ошибка, которая разрешится сама собой.

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

Поиск журналов

Как только вы освоитесь с мониторингом своих интеграций с помощью метрик, следующим шагом станет устранение конкретных ошибок с помощью Cloud Logging . Журнал ошибок — это запись в формате JSON с полями, содержащими полезную информацию, такую ​​как время, код ошибки и сведения об исходном намерении умного дома.

В Google Cloud есть несколько систем, которые постоянно отправляют журналы в ваш проект. Вам нужно писать запросы, чтобы фильтровать логи и находить те, которые вам нужны. Запросы могут основываться на временном диапазоне , ресурсе , серьезности журнала или настраиваемых записях.

Запрос журналов облака

Вы можете использовать кнопки запросов, чтобы создать собственные фильтры.

Создание запросов к журналу 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 , которое поможет вам эффективно протестировать изменения.

Учебные ресурсы

В этом документе описаны действия по устранению ошибок в действиях «Умный дом». Вы также можете проверить наши кодовые лаборатории, чтобы узнать больше об отладке: