Google Cloud udostępnia narzędzia do monitorowania niezawodności projektów za pomocą Google Cloud Monitoring oraz do debugowania problemów za pomocą Google Cloud Logging dzienników błędów. Za każdym razem, gdy podczas realizacji intencji użytkownika wystąpi błąd, potok Google Home Analytics rejestruje ten błąd w Twoich statystykach i publikuje dziennik błędów 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 dziennikach 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żywać 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 dla użytkowników.Cloud-to-cloud 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 skuteczności w zestawieniu błędów wyświetla się kod błędu. W tabeli poniżej możesz zobaczyć błędy oznaczone przez Google Home platform oraz sposoby ich rozwiązywania.
Typowe kody błędów platformy
Oto kilka typowych kodów błędów, które mogą pojawiać się w logach 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 |
|---|---|---|
AGENT_ISSUE |
Wystąpił ogólny problem z agentem w chmurze partnera.
Sprawdź, czy w logach realizacji nie ma nieobsługiwanych wyjątków ani awarii. |
Tak |
AGENT_UNAVAILABLE_ERROR |
Google nie udało się nawiązać połączenia z adresem URL realizacji partnera.
Sprawdź, czy serwer jest online, zapora nie blokuje Google, a adres URL jest prawidłowy. |
Tak |
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, połączone z internetem i zsynchronizowane. |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google otrzymało od Twojej usługi kod błędu HTTP 5xx.
Użyj requestId w Google Cloud Logging, aby sprawdzić
logi usługi inteligentnego domu. Sprawdź awarie serwera, przekroczenia limitu czasu,
lub błędy bramy 502/503.
|
|
COMMAND_FAILED |
Podczas wykonywania polecenia wystąpił ogólny błąd.
Aby znaleźć przyczynę główną, sprawdź logi realizacji pod kątem konkretnego requestId
aby znaleźć przyczynę główną.
|
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_ROBOTED |
Adres URL realizacji jest zablokowany przez plik robots.txt lub filtry zabezpieczeń.
Sprawdź, czy 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 usługa adresu URL punktu końcowego jest stabilna, prawidłowa i publicznie dostępna oraz czy działa. 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ą one zgodne z wymaganymi cechami. |
Tak |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
Chmura partnera wskazuje, że użytkownik odłączył swoje konto.
Sprawdź, czy 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.
Sprawdź, czy tokeny są prawidłowe 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 wyświetlanie”. |
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).
Sprawdź, czy 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ł, a 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 wzrosła 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 przez 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.
Sprawdź, czy 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 pod kątem zgodności z dokumentacją 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 żą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.
Sprawdź, czy odpowiedź zawiera każdy ID podany 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
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 wewnętrzny błąd 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 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. Dziennik błędów 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. Aby filtrować logi i znajdować te, których potrzebujesz, musisz pisać zapytania. Zapytania mogą być oparte na zakresie czasu, zasobie, ważności logu lub wpisach niestandardowych.
Aby tworzyć filtry własne, 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, Informacyjny, Debugowanie, i innych.
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 urządzenia typu 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 pokazuje, jak skutecznie testować zmiany.Test Suite
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 też w naszych ćwiczeniach z programowania:
- Ćwiczenia z programowania dotyczące debugowania inteligentnego domu: krótki przewodnik po debugowaniu integracji inteligentnego domu z chmurą.
- Ćwiczenie w Codelabs dotyczące debugowania lokalnej integracji inteligentnego domu: krótki przewodnik po debugowaniu lokalnej integracji inteligentnego domu.