Rozwiązywanie problemów z błędami integracji

Z chmury do chmury    Matter

Google Cloud zapewnia narzędzia do monitorowania niezawodności projektów za pomocą Google Cloud Monitoring i debugowania problemów z logami błędów Google Cloud Logging. Za każdym razem, gdy nie uda się zrealizować intencji użytkownika, potok Google Home Analytics rejestruje to niepowodzenie w Twoich danych i publikuje dziennik błędów w dziennikach projektu.

Rozwiązywanie problemów z błędami składa się z 2 etapów:

  1. Monitoruj stan projektów za pomocą danych dotyczących inteligentnego domu.
  2. Zbadaj problemy, sprawdzając szczegółowe opisy błędów w logach błędów.

Proces jest podobny w przypadku integracji lokalnej za pomocą Local Home SDK. Gdy opanujesz proces rozwiązywania problemów, możesz łatwo przełączać się między danymi i logami, aby uzyskać statystyki dotyczące błędów.

Opcjonalnie możesz przetestować akcję, udostępniając ją innym użytkownikom. Pamiętaj o odpowiednim obsługiwaniu błędów i wyjątków.

Błędy monitorowania

Aby uzyskać dostęp do danych projektu, możesz użyć Google Cloud Monitoring dashboards. Istnieje kilka kluczowych wykresów, które są szczególnie przydatne do monitorowania jakości i debugowania:

  • Wykres Wskaźnik sukcesu to pierwszy wykres, od którego należy zacząć monitorowanie niezawodności projektów. Spadki na tym wykresie mogą wskazywać na przerwę w działaniu usługi dla 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 95 centyl czasu oczekiwania jest ważnym wskaźnikiem wydajności integracji Cloud-to-cloud dla użytkowników. Nagłe wahania na tym wykresie mogą wskazywać, że Twoje systemy nie nadążają z obsługą żądań. Zalecamy okresowe sprawdzanie tego wykresu, aby wykryć nieoczekiwane zachowania.
  • Wykresy Zestawienie błędów są najbardziej przydatne podczas rozwiązywania problemów z integracjami. W przypadku każdego błędu wyróżnionego na wykresie odsetka sukcesów w zestawieniu błędów wyświetlany jest kod błędu. W tabeli poniżej znajdziesz błędy oznaczone przez Google Home platform (GHP) i sposoby 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 zidentyfikować problemy wykryte przez GHP. Informacje o rozwiązywaniu problemów znajdziesz w tabeli poniżej. Pełną listę kodów błędów znajdziesz w artykule Błędy i wyjątki.

Kod błędu Opis Działanie partnera
AGENT_ISSUE Wystąpił ogólny problem z agentem chmury partnera.

Sprawdź, czy w logach realizacji nie ma nieobsługiwanych wyjątków lub awarii. 		Tak
AGENT_UNAVAILABLE_ERROR Google nie udało się połączyć z adresem URL realizacji partnera.

Sprawdź, czy serwer jest online, zapora sieciowa nie blokuje Google, a adres URL jest prawidłowy. 		Tak
COMMAND_FAILED Podczas wykonywania polecenia wystąpił ogólny błąd.

Aby znaleźć główną przyczynę, sprawdź logi realizacji pod kątem konkretnego błędu requestId. 		Tak
EXECUTION_BACKEND_FAILURE_URL_ERROR Google otrzymało błąd HTTP 4xx (inny niż 401) z Twojej realizacji.

Sprawdź, czy w logach serwera WWW nie ma odpowiedzi 403, 404 lub 400. 		Tak
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT Podczas próby połączenia się 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. 		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 robotów i usług Google. 		Tak
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google otrzymało błąd HTTP 5xx z Twojej usługi realizacji.

Upewnij się, że usługa adresu URL punktu końcowego jest stabilna, prawidłowa i publicznie dostępna oraz że działa. Użyj requestId w Google Cloud Logging, aby sprawdzić logi usługi inteligentnego domu. 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 ściśle zgodna ze schematami intencji. 		Tak
EXECUTION_GAL_BAD_3P_RESPONSE Nie udało się połączyć kont z powodu nieprawidłowego formatu 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 tego działania.

Sprawdź zakresy, o które prosisz podczas uwierzytelniania OAuth, i upewnij się, że odpowiadają one wymaganym cechom. 		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 tokeny 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 pozostają ważne i zsynchronizowane, odpowiednio obsługuj zmiany stanu konta i wymagaj od użytkowników ponownego połączenia konta, jeśli tokeny zostaną unieważnione.
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P Integracja jest w stanie tylko do odczytu po stronie partnera.

Sprawdź, czy konto użytkownika nie jest zawieszone lub nie znajduje się w trybie konserwacji „tylko wyświetlanie”. 		Tak
EXECUTION_GAL_UNLINKED_BY_3P Konto zostało odłączone przez usługę innej firmy.

Sprawdź, dlaczego użytkownik został rozłą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ładniowych, brakujących nawiasów lub nieprawidłowych znaków. 		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 Google Cloud Logging, aby sprawdzić logi usługi inteligentnego domu.
INVALID_JSON Struktura odpowiedzi jest nieprawidłowa (np. brakuje wymaganych pól).

Sprawdź poprawność odpowiedzi, porównując ją ze schematami JSON intencji. 		Tak
MALFORMED_JSON Struktura JSON jest uszkodzona (np. niezamknięte ciągi znaków lub obiekty).

Upewnij się, że realizacja zamówień używa standardowej biblioteki JSON do serializacji odpowiedzi. 		Tak
NOT_IMPLEMENTED Partner nie zaimplementował żądanej intencji ani cechy.

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 kod błędu HTTP 401 z Twojej usługi.

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 odświeżenia tokena.
PARTNER_RESPONSE_INVALID_ERROR_CODE Zwrócony ciąg znaków errorCode nie znajduje się na liście obsługiwanych przez Google.

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 była typu 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 dla wszystkich żądanych poleceń/urządzeń.

Sprawdź strukturę odpowiedzi, korzystając z 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ć odpowiadający mu wpis 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 parametry ID podane 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 w formacie innym 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 może znaleźć wewnętrznego identyfikatora śledzenia dla żądania.

Zwykle jest to błąd wewnętrzny platformy. Obserwuj, czy nie występują skoki, 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 czas oczekiwania backendu. Sprawdź, czy nie występują powolne zapytania do bazy danych lub regionalne opóźnienia sieci. 		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 błąd przekroczenia limitu czasu.

Sprawdź dzienniki pod kątem przekroczeń limitu czasu usług wewnętrznych między chmurą a centrami urządzeń. 		Tak

Dzienniki wyszukiwania

Gdy już nauczysz się monitorować integracje za pomocą danych, kolejnym krokiem będzie rozwiązywanie konkretnych problemów za pomocą Cloud Logging. Dziennik błędów to wpis w formacie JSON z polami zawierającymi przydatne informacje, takie jak czas, kod błędu i szczegóły dotyczące intencji inteligentnego domu, która go wywołała.

W usłudze Google Cloud działa wiele systemów, które przez cały czas wysyłają logi do Twojego projektu. Musisz napisać zapytania, aby przefiltrować logi i znaleźć te, których potrzebujesz. Zapytania mogą być oparte na zakresie czasu, zasobie, ważności logu lub wpisach niestandardowych.

Wykonaj zapytanie dotyczące logów Cloud

Do tworzenia filtrów niestandardowych możesz używać przycisków zapytania.

Tworzenie zapytań dotyczących logów Cloud

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, a następnie wybierz Projekt akcji Asystenta Google. Spowoduje to dodanie do zapytania filtra, który wyświetli logi pochodzące z Twojego projektu.

Użyj przycisku Ważność, aby filtrować według poziomów ważności logów, takich jak Sytuacja alarmowa, Informacje, Debugowanie i inne.

Możesz też użyć pola Zapytanie w Logs Explorer, aby wpisać niestandardowe wpisy. Mechanizm 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 komparatory (<, >=, !=) i operatory logiczne (AND, OR, NOT).

Na przykład niestandardowy wpis poniżej 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 wysyłania zapytań do logów znajdziesz w bibliotece zapytań.

Testowanie poprawek

Po zidentyfikowaniu błędów i wprowadzeniu poprawek zalecamy dokładne przetestowanie ich za pomocą Google Home Test Suite. Udostępniamy przewodnik użytkownika, który opisuje, jak korzystać z Test Suite i skutecznie testować zmiany.

Materiały szkoleniowe

W tym dokumencie znajdziesz instrukcje rozwiązywania problemów z akcją inteligentnego domu. Możesz też zapoznać się z naszymi ćwiczeniami, aby dowiedzieć się więcej o debugowaniu:

Wstecz
Cloud Logging