Google Cloud udostępnia narzędzia do monitorowania niezawodności projektów za pomocą Google Cloud Monitoring oraz do rozwiązywania problemów 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 wszelkich nieprawidłowości po każdej zmianie lub aktualizacji projektu.
- Wykres Opóźnienie 95. percentyla to ważny wskaźnik wydajności integracji typu chmura-chmura 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 skuteczności w zestawieniu 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ź, czy w logach realizacji nie ma nieobsłużonych 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, online 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.
Sprawdź logi realizacji pod kątem konkretnego requestId
aby znaleźć 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_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 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ą 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ą 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).
Upewnij się, że 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 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.
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 innych 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 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 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 koncentratorami 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 znaleźć te, których potrzebujesz. Zapytania mogą być oparte na zakresie czasu, zasobie, ważności logu lub wpisach niestandardowych.
Aby utworzyć filtry własne, możesz użyć 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
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 wpis niestandardowy poniżej 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 pokazuje, jak skutecznie testować zmiany.Test Suite
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 chmury inteligentnego domu.
- Debugowanie lokalnej integracji inteligentnego domu w Codelabs: krótki przewodnik (dla początkujących) dotyczący debugowania lokalnej integracji inteligentnego domu.