Rozwiązywanie problemów z błędami integracji

Chmura-chmura    Matter

Google Cloud udostępnia narzędzia do monitorowania niezawodności projektów za pomocą Google Cloud Monitoring i rozwiązywania problemów z Google Cloud Logging dziennikami błędów. Za każdym razem, gdy nie uda się zrealizować intencji użytkownika, potok Google Home Analytics rejestruje ten błąd w Twoich danych i publikuje dziennik błędów w logach projektu.

Rozwiązywanie błędów składa się z 2 etapów:

  1. Monitoruj stan projektów za pomocą wskaźników inteligentnego domu.
  2. Sprawdź szczegółowe opisy błędów w logach, aby rozwiązać problemy.

Proces jest podobny w przypadku integracji lokalnej za pomocą ikony Local Home SDK. Gdy opanujesz proces rozwiązywania problemów, możesz łatwo przełączać się między danymi a logami, aby uzyskać informacje o błędach.

Opcjonalnie możesz przetestować działanie, udostępniając je innym użytkownikom. Pamiętaj, aby odpowiednio obsługiwać błędy i wyjątki.

Monitorowanie błędów

Aby uzyskać dostęp do danych projektu, możesz użyć Google Cloud Monitoring dashboards. Istnieją kluczowe wykresy, które są szczególnie przydatne do monitorowania jakości i debugowania:

  • Wykres Odsetek sukcesów to pierwszy wykres, od którego należy zacząć monitorowanie niezawodności projektów. Spadki na tym wykresie mogą wskazywać na awarię u części lub wszystkich użytkowników. Zalecamy uważne monitorowanie tego wykresu pod kątem wszelkich nieprawidłowości po każdej zmianie lub aktualizacji projektu.
  • Wykres 95 centyla czasu oczekiwania to ważny wskaźnik tego, jak integracja Cloud-to-cloud działa w przypadku Twoich użytkowników. Nagłe wahania na tym wykresie mogą oznaczać, że Twoje systemy nie nadążają z obsługą żądań. Aby wykryć nieoczekiwane zachowania, warto regularnie sprawdzać ten wykres.
  • Wykresy Podział błędów są najbardziej przydatne podczas rozwiązywania problemów z integracjami. W przypadku każdego błędu wyróżnionego na wykresie procentowym sukcesu w zestawieniu błędów wyświetlany jest kod błędu. W tabeli poniżej znajdziesz błędy oznaczone przez Google Home platform oraz sposoby ich rozwiązywania.

Typowe kody błędów platformy

Oto niektóre typowe kody błędów, które mogą pojawić się w dziennikach projektu, aby wskazywać problemy wykryte przez Google Home platform. Informacje o rozwiązywaniu problemów znajdziesz w tabeli poniżej. Pełną listę kodów błędów znajdziesz w sekcji Błędy i wyjątki.

Kod błędu Opis Działanie partnera
ACTION_NOT_AVAILABLE Polecenie jest nieprawidłowe w obecnym stanie urządzenia (np. „Ustaw temperaturę”, gdy urządzenie jest wyłączone).

Sprawdź w realizacji logikę cech urządzenia i jego aktualnego stanu. 		Tak
AGENT_ISSUE Wystąpił ogólny problem z agentem w chmurze partnera.

Sprawdź w logach realizacji, czy nie ma nieobsłużonych wyjątków lub awarii. 		Tak
AGENT_UNAVAILABLE_ERROR Nie udało się nawiązać połączenia z adresem URL realizacji partnera.

Sprawdź, czy serwer jest online, zapora sieciowa nie blokuje Google, a adres URL jest prawidłowy. 		Tak
APP_LAUNCH_FAILED Nie udało się uruchomić aplikacji innej firmy na urządzeniu docelowym.

Sprawdź identyfikator aplikacji i upewnij się, że aplikacja jest obsługiwana na docelowym sprzęcie. 		Tak
AUTH_EXPIRED Token dostępu OAuth wygasł i nie można go odświeżyć.

Sprawdź rotację tokena odświeżania i upewnij się, że użytkownik nie cofnął dostępu. 		Tak
BACKEND_FAILURE_URL_TIMEOUT Podczas próby uzyskania dostępu do Twojej usługi przekroczono limit czasu żądania Google.

Sprawdź, czy usługa jest dostępna online, akceptuje połączenia i nie jest przeciążona. Sprawdź też, czy urządzenie docelowe jest włączone, połączone z internetem i zsynchronizowane.
BACKEND_FAILURE_URL_UNREACHABLE Google otrzymało z Twojej usługi kod błędu HTTP 5xx.

Użyj requestId w Google Cloud Logging, aby sprawdzić logi usługi inteligentnego domu.
CHANNEL_SWITCH_FAILED Nie udało się przełączyć urządzenia na wybrany kanał komunikacji.

Sprawdź nazwy i numery kanałów oraz stan subskrypcji użytkownika. 		Tak
CHARGER_ISSUE Urządzenie zgłasza problem sprzętowy z systemem ładowania.

Partner powinien sprawdzić telemetrię na poziomie sprzętu i stan baterii. 		Tak
CHECK_PARTNER_APP Błąd wymaga otwarcia aplikacji partnera przez użytkownika w celu rozwiązania problemu.

Użyj tego kodu w przypadku błędów wymagających złożonej interakcji z interfejsem (np. aktualizacji oprogramowania układowego). 		Tak
COMMAND_FAILED Podczas wykonywania polecenia wystąpił ogólny błąd.

Sprawdź logi realizacji, aby znaleźć konkretny requestId i ustalić główną przyczynę. 		Tak
COMMAND_INSERT_FAILED Google nie udało się dodać polecenia do kolejki ani go przetworzyć.

Sprawdź wydajność zapisu w bazie danych lub logikę wewnętrznego kolejkowania poleceń. 		Tak
DEVICE_NOT_FOUND Identyfikator urządzenia w żądaniu nie istnieje po stronie partnera.

Upewnij się, że chmura wywołuje requestSync, gdy użytkownik dodaje lub usuwa urządzenia. 		Tak
ERROR_STATUS Odpowiedź wskazywała na nieokreślony stan „BŁĄD” bez kodu.

Zawsze uwzględniaj konkretny ciąg znaków errorCode, aby ulepszyć dane TTS użytkownika i dane panelu. 		Tak
EXECUTION_BACKEND_FAILURE_URL_ERROR Google otrzymało od Twojego systemu realizacji zamówień błąd HTTP 4xx (inny niż 401).

Sprawdź logi serwera WWW pod kątem odpowiedzi 403, 404 lub 400. 		Tak
EXECUTION_BACKEND_FAILURE_URL_ROBOTED Adres URL realizacji jest blokowany przez plik robots.txt lub filtry zabezpieczeń.

Upewnij się, że punkt końcowy realizacji jest dostępny dla robotów indeksujących i usług Google. 		Tak
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google otrzymało z Twojej usługi realizacji zamówień błąd HTTP 5xx.

Sprawdź, czy nie występują awarie serwera, przekroczenia limitu czasu lub błędy bramy 502/503. 		Tak
EXECUTION_BAILOUT_INVALID_RESPONSE Odpowiedź JSON była tak nieprawidłowa, że przetwarzanie zostało przerwane.

Użyj walidatora JSON, aby sprawdzić, czy odpowiedź jest zgodna ze schematami intencji. 		Tak
EXECUTION_GAL_BAD_3P_RESPONSE Nie udało się połączyć kont z powodu nieprawidłowego formatu w odpowiedzi tokena.

Sprawdź, czy format odpowiedzi serwera OAuth jest zgodny z wymaganiami Google. 		Tak
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES Konto użytkownika nie ma uprawnień wymaganych do wykonania tej czynności.

Sprawdź zakresy, o które aplikacja prosi podczas uwierzytelniania OAuth, i upewnij się, że są zgodne z wymaganymi cechami. 		Tak
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P Chmura partnera wskazuje, że użytkownik odłączył swoje konto.

Upewnij się, że agentUserId mapowanie jest stabilne i nie zostało usunięte. 		Tak
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P Integracja jest w stanie tylko do odczytu po stronie partnera.

Sprawdź, czy konto użytkownika jest zawieszone lub w trybie konserwacji „tylko wyświetlanie”. 		Tak
EXECUTION_GAL_UNLINKED_BY_3P Konto zostało odłączone przez usługę innej firmy.

Sprawdź, dlaczego użytkownik został odłączony (np. z powodu resetowania ustawień bezpieczeństwa). 		Tak
EXECUTION_INVALID_JSON Nie udało się przeanalizować przez Google ładunku odpowiedzi JSON.

Sprawdź, czy w odpowiedzi nie ma błędów składniowych, brakujących nawiasów lub nieprawidłowych znaków. 		Tak
FAULTY_BATTERY Sprzęt urządzenia zgłasza, że bateria jest uszkodzona lub rozładowana.

Poproś użytkownika za pomocą funkcji TTS lub aplikacji o wymianę baterii. 		Tak
FUNCTION_NOT_SUPPORTED Żądany tryb lub funkcja nie jest obsługiwana przez urządzenie.

Upewnij się, że SYNC odpowiedź dokładnie odzwierciedla możliwości urządzenia. 		Tak
HARD_ERROR Trwały błąd, którego nie można rozwiązać bez ręcznej interwencji.

Użyj tej opcji w przypadku trwałych awarii sprzętu lub nie do odzyskania stanów konta. 		Tak
INVALID_AUTH_TOKEN Google otrzymało z Twojej usługi kod błędu HTTP 401.

Token dostępu nie wygasł, ale Twoja usługa go unieważniła. Użyj requestId w Cloud Logging, aby sprawdzić logi usługi inteligentnego domu.
INVALID_JSON Struktura odpowiedzi jest nieprawidłowa (np. brakuje wymaganych pól).

Sprawdź poprawność odpowiedzi na podstawie schematów JSON intencji. 		Tak
LOCK_FAILURE Nie udało się ustawić inteligentnego zamka w żądanym stanie.

Sprawdź, czy nie ma fizycznych blokad, czy urządzenie ma wystarczająco dużo energii i czy silnik zamka nie uległ awarii. 		Tak
MALFORMED_JSON Struktura JSON jest uszkodzona (np. nie ma zamkniętych ciągów znaków lub obiektów).

Sprawdź, czy usługa realizująca zamówienie używa standardowej biblioteki JSON do serializacji odpowiedzi. 		Tak
MISSING_STATE Odpowiedź QUERY nie zawierała żądanego stanu urządzenia.

Upewnij się, że wszystkie cechy zdefiniowane w SYNC są uwzględnione w każdej odpowiedzi QUERY. 		Tak
NETWORK_PROFILE_NOT_RECOGNIZED Urządzenie nie rozpoznaje żądanego profilu sieciowego.

Sprawdź, czy ciąg nazwy profilu jest zgodny z obsługiwanymi profilami w odpowiedzi SYNC. 		Tak
NOT_IMPLEMENTED Żądany zamiar lub cecha nie zostały zaimplementowane przez partnera.

W odpowiedzi SYNC uwzględniaj tylko te cechy, które zostały w pełni wdrożone. 		Tak
OAUTH_RECONNECT_CALL_TO_ACTION Wysyła do użytkownika powiadomienie z prośbą o ponowne połączenie konta.

Użyj tego kodu, gdy sesja użytkownika zostanie unieważniona i wymaga ręcznego ponownego uwierzytelnienia OAuth. 		Tak
OPEN_AUTH_FAILURE Token dostępu użytkownika wygasł i Google nie może go odświeżyć lub Google otrzymało z Twojej usługi kod błędu HTTP 401.

Jeśli zauważysz wzrost liczby wystąpień tego kodu, sprawdź, czy nie wzrosła też liczba błędów związanych z intencjami dotyczącymi inteligentnego domu lub żądaniami tokena odświeżania.
PARTNER_RESPONSE_INVALID_ERROR_CODE Zwrócony ciąg znaków errorCode nie znajduje się na liście obsługiwanych ciągów znaków Google.

Map your internal errors to the Official Error List. 		Tak
PARTNER_RESPONSE_INVALID_PAYLOAD Pole payload w odpowiedzi nie jest prawidłowym obiektem JSON.

Sprawdź strukturę główną odpowiedzi dotyczącej realizacji zamówienia. 		Tak
PARTNER_RESPONSE_INVALID_STATUS Odpowiedź status nie miała wartości SUCCESS, ERROR ani OFFLINE.

Upewnij się, że każdy wynik urządzenia w odpowiedzi zawiera prawidłowy ciąg znaków stanu. 		Tak
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Odpowiedź nie zawierała wyników dla wszystkich żądanych poleceń/urządzeń.

Każdy element w tablicy commands w żądaniu musi mieć odpowiedni wpis w odpowiedzi. 		Tak
PARTNER_RESPONSE_MISSING_DEVICE W odpowiedzi pominięto konkretne urządzenie, o które prosiło Google.

Upewnij się, że odpowiedź zawiera wszystkie znaczniki ID podane w ładunku żądania. 		Tak
PARTNER_RESPONSE_MISSING_PAYLOAD W odpowiedzi brakuje wymaganego pola payload.

Sprawdź, czy obiekt JSON najwyższego poziomu zawiera klucz payload. 		Tak
PARTNER_RESPONSE_NOT_OBJECT Nie udało się przeanalizować całej odpowiedzi jako obiektu JSON.

Sprawdź, czy w treści odpowiedzi HTTP nie ma znaków końcowych ani treści innych niż JSON. 		Tak
PROTOCOL_ERROR W protokole komunikacyjnym wystąpił błąd.

Sprawdź problemy z nagłówkami HTTP lub nieudane uzgadnianie połączenia SSL/TLS. 		Tak
RELINK_REQUIRED Aby nadal korzystać z integracji, użytkownik musi ponownie połączyć swoje konto.

Upewnij się, że serwer zwraca ten kod, gdy token odświeżania jest trwale nieważny. 		Tak
REQUEST_ID_NOT_FOUND Nie udało nam się znaleźć wewnętrznego identyfikatora śledzenia żądania.

Zwykle jest to błąd wewnętrzny platformy. Obserwuj nagłe wzrosty i skontaktuj się z zespołem pomocy. 		Tak
RESOURCE_UNAVAILABLE Żądany zasób (urządzenie lub cecha) jest niedostępny.

Sprawdź, czy urządzenie jest „Zajęte” lub zostało tymczasowo wyłączone. 		Tak
RESPONSE_TIMEOUT Usługa realizacji nie odpowiedziała w ciągu 9 sekund.

Zoptymalizuj opóźnienie backendu. Sprawdź, czy nie występują powolne zapytania do bazy danych lub regionalne opóźnienia sieci. 		Tak
RESPONSE_UNAVAILABLE Nie otrzymaliśmy odpowiedzi z adresu URL realizacji zamówienia partnera.

Sprawdź, czy usługa działa, a punkt końcowy nie ulega awarii. 		Tak
SCENE_CANNOT_BE_APPLIED Nie udało się aktywować żądanej sceny (np. z powodu braku urządzeń).

Sprawdź wewnętrzny stan scen użytkownika w chmurze partnera. 		Tak
STREAM_UNPLAYABLE Nie udało się uruchomić strumienia z kamery lub wystąpił w nim błąd.

Sprawdź sygnalizację WebRTC/HLS i upewnij się, że adres URL strumienia jest prawidłowy. 		Tak
TIMEOUT Podczas przetwarzania intencji wystąpił ogólny limit czasu.

Sprawdź logi dotyczące wewnętrznych limitów czasu usługi między chmurą a hubami urządzeń. 		Tak
TRANSIENT_ERROR Błąd przejściowy to błąd, który sam się rozwiąże.

Najczęściej błędy te objawiają się przerwaniem połączenia z urządzeniem lub usługą. Dotyczy to też sytuacji, gdy nie można otworzyć nowych połączeń z serwerem.
UNABLE_TO_LOCATE_DEVICE Nie udało się znaleźć urządzenia za pomocą cechy Lokalizator (np. ping się nie powiódł).

Sprawdź lokalne połączenia urządzenia (Wi-Fi/Bluetooth). 		Tak
UNABLE_TO_RING_DEVICE Nie udało się uzyskać dostępu do urządzenia, aby włączyć dzwonek lub alert.

Sprawdź stan alertu/głośnika i poziomy głośności urządzenia. 		Tak
UNABLE_TO_SILENCE_DEVICE Urządzenie nie mogło zatrzymać aktywnego alertu ani dzwonka.

Sprawdzanie błędów komunikacji między chmurą a urządzeniem fizycznym. 		Tak
UNEXPECTED_ERROR_CHECK_DEVICE_APP Wystąpił nieprzewidziany błąd. Użytkownik powinien sprawdzić aplikację partnera.

Używaj tego kodu jako ogólnego kodu błędu, który nie ma konkretnego odpowiednika obsługiwanego przez Google. 		Tak
UNKNOWN_ERROR Ogólny błąd bez dodatkowych szczegółów.

Zastąp ten kod bardziej szczegółowymi kodami błędów, aby ułatwić rozwiązywanie problemów. 		Tak
UNLOCK_FAILURE Inteligentny zamek nie mógł przejść w stan „Odblokowany”.

Sprawdź, czy nie doszło do zacięcia sprzętu, czy bateria nie jest bliska wyczerpania lub czy nie wprowadzono nieprawidłowego kodu PIN. 		Tak

Dzienniki wyszukiwania

Gdy już opanujesz monitorowanie integracji za pomocą wskaźników, kolejnym krokiem będzie rozwiązywanie konkretnych błędów za pomocą Cloud Logging. Dziennik błędów to wpis w formacie JSON zawierający przydatne informacje, takie jak czas, kod błędu i szczegóły dotyczące pierwotnego zamiaru związanego z inteligentnym domem.

W usłudze Google Cloud działa wiele systemów, które przez cały czas wysyłają logi do Twojego projektu. Musisz napisać zapytania, aby filtrować logi i znaleźć te, których potrzebujesz. Zapytania mogą być oparte na zakresie czasu, zasobie, ważności dziennika lub wpisach niestandardowych.

Wysyłanie zapytań do logów Cloud

Aby utworzyć filtry własne, możesz użyć przycisków zapytań.

Tworzenie zapytań dotyczących logów Cloud

Aby określić zakres czasowy, kliknij przycisk wyboru zakresu czasowego i wybierz jedną z dostępnych opcji. Spowoduje to odfiltrowanie logów i wyświetlenie tych, które pochodzą z wybranego zakresu czasu.

Aby określić zasób, kliknij menu Zasób, a następnie wybierz Projekt działania Asystenta Google. Spowoduje to dodanie do zapytania filtra, który będzie wyświetlać logi pochodzące z Twojego projektu.

Użyj przycisku Waga, aby filtrować logi według poziomu ważności, np. Alarm, Informacje, Debugowanie i inne.

Możesz też użyć pola Zapytanie w sekcji Logs Explorer, aby wprowadzić niestandardowe wpisy. Silnik zapytań używany przez to pole obsługuje zarówno podstawowe zapytania, takie jak dopasowywanie ciągów znaków, jak i bardziej zaawansowane typy zapytań, w tym operatory porównania (<, >=, !=) i operatory logiczne (AND, OR, NOT).

Na przykład poniższy wpis niestandardowy zwróci błędy pochodzące z LIGHT typu urządzenia:

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

Więcej przykładów skutecznego wyszukiwania w logach znajdziesz w bibliotece zapytań.

Testowanie poprawek

Po zidentyfikowaniu błędów i zastosowaniu aktualizacji w celu ich naprawienia zalecamy dokładne przetestowanie poprawek za pomocą Google Home Test Suite. Przygotowaliśmy przewodnik użytkownika dotyczący korzystania z Test Suite, który zawiera instrukcje skutecznego testowania zmian.

Materiały szkoleniowe

W tym dokumencie znajdziesz instrukcje rozwiązywania problemów z błędami w działaniu inteligentnego domu. Więcej informacji o debugowaniu znajdziesz w naszych codelabach:

Wstecz
Cloud Logging