Rozwiązywanie problemów z integracją spraw

refresh_date: 2023-01-06

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.

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ć 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.
  • 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 procentu 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 występują nieobsłużone wyjątki lub awarie. 		Tak
AGENT_UNAVAILABLE_ERROR Nie udało się nawiązać połączenia z adresem URL realizacji partnera.

Sprawdź, czy serwer jest online, zapora nie blokuje Google i czy 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 nawiązania połączenia z usługą upłynął 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 Cloud Logging w Google Cloud, aby sprawdzić logi usługi inteligentnego domu. Sprawdź, czy nie występują awarie serwera, przekroczenia limitu czasu lub błędy bramy 502/503.
CHANNEL_SWITCH_FAILED Nie udało się przełączyć urządzenia na wybrany kanał multimedialny.

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żywaj 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 backend zawsze synchronizuje Home Graph. Wywołuj requestSync za każdym razem, gdy dodawane lub usuwane są urządzenia. 		Tak
ERROR_STATUS Odpowiedź wskazywała na nieokreślony stan „BŁĄD” bez kodu.

Zawsze uwzględniaj konkretny errorCode ciąg znaków, aby ulepszyć dane TTS użytkownika i dane panelu. 		Tak
EXECUTION_BACKEND_FAILURE_URL_ERROR Google otrzymało z 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 indeksatorów i usług Google. 		Tak
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google otrzymało z Twojej usługi realizacji zamówień błąd HTTP 5xx.

Upewnij się, że adres URL punktu końcowego jest stabilny, prawidłowy i publicznie dostępny, a usługa jest uruchomiona. Dodaj kontrole stanu i obsługę ponownych prób. 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 upewnić się, że 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 żądane 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 do odczytu”. 		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). Upewnij się, że serwer OAuth partnera prawidłowo odpowiada na żądania refresh_token Google dotyczące bezproblemowego wydawania nowych tokenów dostępu. 		Tak
EXECUTION_INVALID_JSON Nie udało się przeanalizować przez Google całej 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.
HARD_ERROR Trwałe niepowodzenie, którego nie można rozwiązać bez ręcznej interwencji.

Użyj tej opcji w przypadku trwałych awarii sprzętu lub nieodwracalnych 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 zamek ma wystarczająco dużo energii i czy nie doszło do awarii silnika. 		Tak
MALFORMED_JSON Struktura JSON jest uszkodzona (np. nie zamknięto 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 lub EXECUTE i zwracaj wszystkie wymagane stany cech, nawet jeśli nie uległy zmianie. 		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, 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 statusu. 		Tak
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Odpowiedź nie zawierała wyników dla wszystkich żądanych poleceń/urządzeń.

Sprawdź strukturę odpowiedzi w dokumentacji dla deweloperów Google Home. Sprawdź, czy odpowiedź nie jest obcinana lub czy nie zwraca pustej treści z powodu wewnętrznego błędu serwera. 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. Sprawdź, czy payload.commands[] jest prawidłowym obiektem JSON zawierającym identyfikatory, stan i opcjonalne stany. 		Tak
PROTOCOL_ERROR W protokole komunikacyjnym wystąpił błąd.

Sprawdź problemy z nagłówkami HTTP lub nieudane uzgodnienia połączenia SSL/TLS. 		Tak
RELINK_REQUIRED Aby nadal korzystać z integracji, użytkownik musi ponownie połączyć 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 opóźnienia w sieci regionalnej. 		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ł 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ę utratą 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 Locator (np. ping się nie powiódł).

Sprawdź lokalną łączność urządzenia (Wi-Fi/Bluetooth). 		Tak
UNABLE_TO_RING_DEVICE Nie udało się wywołać dzwonka ani alertu na urządzeniu.

Sprawdź stan alertu/głośnika i poziom 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.

Dodaj odpowiednie mapowanie błędów, zabezpieczenia i rejestrowanie, aby znane błędy zwracały konkretne kody błędów zamiast ogólnych. 		Tak
UNLOCK_FAILURE Nie udało się odblokować zamka.

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 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 logu lub wpisach niestandardowych.

Wysyłanie zapytań do logów Cloud

Aby utworzyć filtry niestandardowe, 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. Alarmowy, Informacyjny, Debugowanie i inne.

Możesz też użyć pola Zapytanie w sekcji Logs Explorer, aby wprowadzić niestandardowe wpisy. Silnik zapytań używany w tym polu 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:

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

Więcej przykładów skutecznych zapytań o logi 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. Udostępniamy 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 dla sprawy