Google Cloud udostępnia narzędzia, które pomogą Ci monitorować niezawodność projektów za pomocą Google Cloud Monitoring i rozwiązywać problemy z Google Cloud Logging logami błędów. Gdy podczas realizacji intencji użytkownika wystąpi błąd, potok Google Home Analytics zapisuje go w Twoich statystykach i publikuje log błędu w logach projektu.
Rozwiązywanie problemów z błędami obejmuje 2 kroki:
- Monitoruj stan projektów za pomocą statystyk inteligentnego domu.
- Sprawdzaj szczegółowe opisy błędów w logach błędów, aby rozwiązywać problemy.
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 statystyk projektu, możesz użyć Google Cloud Monitoring dashboards. Oto kilka kluczowych wykresów, które są szczególnie przydatne do monitorowania jakości i debugowania:
- Wykres Współczynnik skuteczności 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 nieprawidłowości po każdej zmianie lub aktualizacji projektu.
- Wykres Opóźnienie 95. percentyla to ważny wskaźnik wydajności integracji Cloud-to-cloud dla użytkowników. Nagłe wahania na tym wykresie mogą wskazywać, że Twoje systemy nie są w stanie nadążyć za żądaniami. Zalecamy okresowe sprawdzanie tego wykresu, aby wykryć nieoczekiwane zachowania.
- Wykresy Podział błędów są najbardziej przydatne do rozwiązywania problemów z integracjami. W przypadku każdego błędu wyróżnionego na wykresie procentowym sukcesu w podziale błędów wyświetla się kod błędu. W tabeli poniżej znajdziesz informacje o błędach oznaczonych przez Google Home platform oraz o sposobach ich rozwiązywania.
Typowe kody błędów platformy
Oto kilka typowych kodów błędów, które mogą pojawić się w logach projektu, aby pomóc Ci zidentyfikować 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 |
|---|---|---|
AGENT_ISSUE |
Wystąpił ogólny problem z agentem w chmurze partnera.
Sprawdź logi realizacji pod kątem nieobsługiwanych wyjątków lub awarii. |
Tak |
AGENT_UNAVAILABLE_ERROR |
Google nie może uzyskać dostępu do adresu URL realizacji partnera.
Sprawdź, czy serwer jest online, zapora nie blokuje Google, a adres URL jest prawidłowy. |
Tak |
COMMAND_FAILED |
Podczas wykonywania polecenia wystąpił ogólny błąd.
Sprawdź logi realizacji pod kątem konkretnego requestId
aby znaleźć główną przyczynę.
|
Tak |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google otrzymało od Twojej
realizacji błąd HTTP 4xx (inny niż 401).
Sprawdź logi serwera WWW pod kątem odpowiedzi 403, 404 lub 400. |
Tak |
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT |
Podczas próby nawiązania połączenia z Twoją usługą upłynął limit czasu żądania Google.
Sprawdź, czy usługa jest online, akceptuje połączenia, i nie jest przeciążona. Sprawdź też, czy urządzenie docelowe jest włączone, online i zsynchronizowane. |
Tak |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
Adres URL realizacji jest zablokowany przez plik robots.txt lub filtry zabezpieczeń.
Upewnij się, że punkt końcowy realizacji jest dostępny dla robotów i usług Google. |
Tak |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google otrzymało od Twojej usługi realizacji błąd HTTP 5xx.
Sprawdź, czy adres URL punktu końcowego jest stabilny, prawidłowy i publicznie dostępny oraz czy usługa działa. Użyj requestId w
Google Cloud Logging, aby sprawdzić logi usługi inteligentnego domu.
Dodaj kontrole stanu i obsługę ponawiania.
Sprawdź awarie serwera, przekroczenia limitu czasu lub błędy bramy 502/503.
|
Tak |
EXECUTION_BAILOUT_INVALID_RESPONSE |
Odpowiedź JSON była tak uszkodzona, ż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ć konta 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 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 mapowanie agentUserId jest stabilne i nie zostało
usunięte.
|
Tak |
EXECUTION_GAL_NOT_FOUND |
Tokeny dostępu i odświeżania użytkownika przechowywane w Google są nieprawidłowe lub
nie można ich odświeżyć, co uniemożliwia uwierzytelnianie i dostęp do
usługi partnera.
Upewnij się, że tokeny są nadal ważne i zsynchronizowane, odpowiednio obsługuj zmiany stanu konta i wymagaj od użytkowników ponownego połączenia konta, jeśli tokeny zostaną odwołane. |
|
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 proaktywnie odłączone przez usługę innej firmy.
Sprawdź, dlaczego użytkownik został odłączony (np. z powodu resetowania zabezpieczeń). Upewnij się, że serwer OAuth partnera prawidłowo odpowiada na żądania refresh_token Google, aby bezproblemowo wydawać nowe tokeny dostępu.
|
Tak |
EXECUTION_INVALID_JSON |
Google nie udało się przeanalizować ładunku odpowiedzi JSON.
Sprawdź, czy w odpowiedzi nie ma błędów składni, brakujących nawiasów lub nieprawidłowych znaków. |
Tak |
INVALID_AUTH_TOKEN |
Google otrzymało od 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 Google Cloud Logging, aby sprawdzić swoje
logi usługi inteligentnego domu.
|
|
INVALID_JSON |
Struktura odpowiedzi jest nieprawidłowa (np. brakuje wymaganych
pól).
Sprawdź poprawność odpowiedzi względem schematów JSON intencji. |
Tak |
MALFORMED_JSON |
Struktura JSON jest uszkodzona (np. nie zamknięto ciągów znaków lub
obiektów).
Upewnij się, że Twoja realizacja używa standardowej biblioteki JSON do serializacji odpowiedzi. |
Tak |
NOT_IMPLEMENTED |
Żądana intencja lub cecha nie została zaimplementowana przez partnera.
W odpowiedzi SYNC uwzględniaj tylko te cechy, które zostały
w pełni zaimplementowane.
|
Tak |
OPEN_AUTH_FAILURE |
Token dostępu użytkownika wygasł i Google nie może go odświeżyć,
lub Google otrzymało od Twojej usługi kod błędu HTTP 401.
Jeśli zauważysz wzrost liczby wystąpień tego kodu, sprawdź, czy nie zwiększyła się też liczba błędów związanych z intencjami inteligentnego domu lub żądaniami tokena odświeżania. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
Zwrócony ciąg errorCode nie znajduje się na liście obsługiwanych kodów Google'a.
Zmapuj błędy wewnętrzne na oficjalną listę błędów. |
Tak |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Pole payload w odpowiedzi nie jest prawidłowym obiektem JSON.
Sprawdź strukturę główną odpowiedzi realizacji. |
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 stanu. |
Tak |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Odpowiedź nie zawierała wyników wszystkich żądanych
poleceń ani urządzeń.
Sprawdź strukturę odpowiedzi względem dokumentacji dla deweloperów Google Home Upewnij się, że odpowiedź nie jest obcinana ani nie zwraca pustej treści z powodu wewnętrznego błędu serwera. Każdy element w tablicy commands żądania 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 każdy ID podany w
ładunku żądania.
|
Tak |
PARTNER_RESPONSE_MISSING_PAYLOAD |
W odpowiedzi brakuje wymaganego pola payload.
Upewnij się, że 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 innej niż JSON. Upewnij się, że payload.commands[] jest prawidłowym obiektem JSON
z identyfikatorami, stanem i opcjonalnymi stanami.
|
Tak |
REQUEST_ID_NOT_FOUND |
Google nie udało się znaleźć wewnętrznego identyfikatora śledzenia żądania.
Zwykle jest to błąd wewnętrzny platformy. Monitoruj pod kątem nagłych wzrostów 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 otrzymano odpowiedzi z adresu URL realizacji partnera.
Sprawdź, czy usługa działa, a punkt końcowy nie ulega awarii. |
Tak |
TIMEOUT |
Podczas przetwarzania intencji wystąpił ogólny limit czasu.
Sprawdź logi pod kątem wewnętrznych limitów czasu usługi między chmurą a hubami urządzeń. |
Tak |
Dzienniki wyszukiwania
Gdy opanujesz monitorowanie integracji za pomocą statystyk, następnym krokiem będzie rozwiązywanie konkretnych błędów za pomocą Cloud Logging. Log błędu to wpis podobny do JSON z polami zawierającymi przydatne informacje, takie jak czas, kod błędu i szczegóły dotyczące intencji inteligentnego domu.
W Google Cloud jest wiele systemów, które przez cały czas wysyłają logi do Twojego projektu. Musisz napisać zapytania, aby filtrować logi i znajdować te, których potrzebujesz. Zapytania mogą być oparte na zakresie czasu, zasobie, ważności logu lub wpisach niestandardowych.
Do tworzenia filtrów własnych możesz używać przycisków zapytań.
Aby określić zakres czasu, kliknij przycisk wyboru zakresu czasu i wybierz jedną z dostępnych opcji. Spowoduje to przefiltrowanie logów i wyświetlenie tych, które pochodzą z wybranego zakresu czasu.
Aby określić zasób, kliknij menu Zasób i 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 Ważność, aby filtrować według poziomów ważności logów: Awaryjny, Informacje, Debugowanie, i inne.
Możesz też użyć pola Zapytanie w Logs Explorer
aby wpisać wpisy niestandardowe. Silnik zapytań używany przez to pole obsługuje zarówno
zapytania podstawowe, 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 typu urządzenia LIGHT:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
Więcej przykładów skutecznego wyszukiwania logów znajdziesz w bibliotece zapytań.
Testowanie poprawek
Gdy zidentyfikujesz błędy i zastosujesz aktualizacje, aby je naprawić, zalecamy dokładne przetestowanie poprawek za pomocą Google Home Test Suite. Udostępniamy przewodnik dla użytkownika, który zawiera instrukcje korzystania z Test Suite i skutecznego testowania zmian.
Materiały szkoleniowe
W tym dokumencie znajdziesz instrukcje rozwiązywania błędów w działaniu inteligentnego domu. Więcej informacji o debugowaniu znajdziesz też w naszych ćwiczeniach z programowania:
- Ćwiczenia z programowania dotyczące debugowania inteligentnego domu: przewodnik dla początkujących dotyczący debugowania integracji inteligentnego domu z chmurą.
- Ćwiczenia z programowania dotyczące debugowania lokalnego inteligentnego domu: przewodnik dla początkujących dotyczący debugowania integracji lokalnego inteligentnego domu.