Rozwiązywanie problemów z integracją

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 logami błędów. Za każdym razem, gdy podczas realizacji intencji użytkownika wystąpi błąd, potok Google Home Analytics rejestruje go w Twoich danych, a w logach projektu publikuje dziennik błędów.

Rozwiązywanie problemów z błędami obejmuje 2 etapy:

  1. Monitoruj stan projektów za pomocą wskaźników inteligentnego domu.
  2. Sprawdź szczegółowe opisy błędów w dziennikach błędów, aby zbadać 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ć 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 Cloud-to-cloud działa w przypadku Twoich użytkowników. Nagłe wahania na tym wykresie mogą wskazywać, ż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 do 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.

Kody błędów platformy

Oto niektóre typowe kody błędów, które mogą pojawić się w dziennikach projektu, aby pomóc Ci zidentyfikować problemy wykryte przez Google Home platform. Informacje o rozwiązywaniu problemów znajdziesz w tabeli poniżej.

Kod błędu Opis
BACKEND_FAILURE_URL_ERROR Google otrzymało z Twojej usługi kod błędu HTTP 4xx inny niż 401.

Użyj requestId w GCP Logging, aby sprawdzić dzienniki usługi inteligentnego domu.
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 GCP Logging, aby sprawdzić dzienniki usługi inteligentnego domu.
DEVICE_NOT_FOUND Urządzenie nie istnieje po stronie usługi partnera.

Zwykle wskazuje to na błąd synchronizacji danych lub warunek wyścigu.
GAL_BAD_3P_RESPONSE Google nie może przeanalizować odpowiedzi z usługi łączenia kont z powodu nieprawidłowego formatu lub wartości w ładunku.

W usłudze requestId w GCP Logging możesz sprawdzić dzienniki błędów w usłudze łączenia kont.
GAL_INTERNAL Podczas próby pobrania tokena dostępu wystąpił błąd wewnętrzny Google.

Jeśli w GCP Logging zauważysz wzrost liczby tych błędów, skontaktuj się z nami, aby uzyskać więcej informacji.
GAL_INVALID_ARGUMENT Podczas próby pobrania tokena dostępu wystąpił błąd wewnętrzny Google.

Jeśli w GCP Logging zauważysz wzrost liczby tych błędów, skontaktuj się z nami, aby uzyskać więcej informacji.
GAL_NOT_FOUND Tokeny dostępu i tokeny odświeżania użytkownika przechowywane w Google zostaną unieważnione i nie będzie można ich już odświeżać. Aby nadal korzystać z Twojej usługi, użytkownik musi ponownie połączyć swoje konto.

Jeśli w GCP Logging zauważysz wzrost liczby tych błędów, skontaktuj się z nami, aby uzyskać więcej informacji.
GAL_PERMISSION_DENIED Wystąpił wewnętrzny błąd Google, gdy udostępnianie tokenów nie jest autoryzowane.

Jeśli w GCP Logging zauważysz wzrost liczby tych błędów, skontaktuj się z nami, aby uzyskać więcej informacji.
GAL_REFRESH_IN_PROGRESS Token dostępu użytkownika wygasł i trwa już inna próba jego odświeżenia.

Nie jest to problem i nie musisz podejmować żadnych działań.
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 usłudze Logging w GCP, aby sprawdzić dzienniki usługi inteligentnego domu.
INVALID_JSON Nie można przeanalizować ani zinterpretować odpowiedzi JSON.

Sprawdź strukturę odpowiedzi JSON pod kątem nieprawidłowej składni, np. niezgodnych nawiasów, brakujących przecinków lub nieprawidłowych znaków.
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 Odpowiedź wskazuje nierozpoznany kod błędu.

Jeśli odpowiedź na Twoją prośbę wskazuje na błąd, użyj jednego z kodów podanych na naszej liście obsługiwanych kodów błędów.
PARTNER_RESPONSE_INVALID_PAYLOAD Nie można przeanalizować pola odpowiedzi payload jako obiektu JSON.

Sprawdź, czy pole ładunku w odpowiedzi na żądanie ma pasujące nawiasy i czy jest prawidłowo sformatowane jako pole JSON.
PARTNER_RESPONSE_INVALID_STATUS Odpowiedź nie wskazuje stanu lub wskazuje nieprawidłowy stan.

Odpowiedzi na żądania realizacji intencji powinny zawierać stan SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Więcej informacji o  obsłudze błędów i wyjątków.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES W odpowiedzi brakuje co najmniej jednego zamiaru obecnego w żądaniu.

Sprawdź, czy odpowiedź wykonania ma prawidłową strukturę i czy zawiera wyniki dla wszystkich intencji z żądania.
PARTNER_RESPONSE_MISSING_DEVICE W odpowiedzi brakuje co najmniej jednego urządzenia, które było obecne w żądaniu.

Sprawdź, czy odpowiedź na żądanie wykonania ma prawidłową strukturę i czy zawiera wszystkie identyfikatory urządzeń z żądania.
PARTNER_RESPONSE_MISSING_PAYLOAD Odpowiedź nie zawiera pola payload.

W odpowiedzi na żądanie uwzględnij pole ładunku. Więcej informacji o prawidłowym tworzeniu odpowiedzi na żądanie wykonania znajdziesz w tym artykule.
PARTNER_RESPONSE_NOT_OBJECT Nie można przeanalizować odpowiedzi jako obiektu JSON.

Sprawdź wszystkie pola w odpowiedzi na żądanie pod kątem niechcianych znaków, niezgodnych nawiasów lub błędów formatowania. Niektóre znaki Unicode mogą być nieobsługiwane. Sprawdź też, czy odpowiedź jest prawidłowo sformatowana jako obiekt JSON.
PROTOCOL_ERROR Nie udało się przetworzyć żądania.

Użyj requestId w Cloud Logging, aby sprawdzić logi usługi inteligentnego domu.
RELINK_REQUIRED Odpowiedź wskazuje na relinkRequired błąd, który powoduje, że użytkownik musi ponownie połączyć konta Google i partnera.

Więcej informacji znajdziesz w sekcji obsługiwane kody błędów.
RESPONSE_TIMEOUT Upłynął limit czasu oczekiwania na odpowiedź.

Czas oczekiwania na wysłanie odpowiedzi wynosi 9 sekund od momentu wysłania żądania. Pamiętaj, aby wysłać odpowiedź w tym czasie.
RESPONSE_UNAVAILABLE Nie otrzymano odpowiedzi lub nie zawiera ona informacji o stanie.

Odpowiedzi na żądania realizacji intencji powinny być zgodne z  dokumentacją dotyczącą inteligentnego domu i zawierać informacje o stanie.
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.

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.

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ń do 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 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 typu urządzenia:

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 wykryciu błędów i wprowadzeniu poprawek zalecamy dokładne przetestowanie ich 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 akcji inteligentnego domu. Więcej informacji o debugowaniu znajdziesz w naszych codelabach: