Rozwiązywanie problemów z integracją spraw

refresh_date: 2023-01-06

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 dziennikami błędów. Za każdym razem, gdy nie uda się zrealizować intencji użytkownika, potok Google Home Analytics rejestruje ten błąd w Twoich danych i publikuje dziennik błędów w logach projektu.

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

  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 rozwiązać problemy.

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.
  • Wykresy Podział błędów są najbardziej przydatne podczas rozwiązywania problemów z integracjami. W przypadku każdego błędu wyróżnionego na wykresie procentowym 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.

Typowe kody błędów platformy

Oto niektóre typowe kody błędów, które mogą pojawić się w dziennikach 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ź w logach realizacji, czy nie występują nieobsłużone wyjątki lub awarie. 		Tak
AGENT_UNAVAILABLE_ERROR 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 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 Google Cloud Logging, aby sprawdzić logi usługi inteligentnego domu. Sprawdź, czy nie występują 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, aby znaleźć konkretny requestId i ustalić główną przyczynę. 		Tak
EXECUTION_BACKEND_FAILURE_URL_ERROR Google otrzymało z Twojego systemu realizacji zamówień 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 blokowany przez plik robots.txt lub filtry zabezpieczeń.

Upewnij się, że punkt końcowy realizacji jest dostępny dla robotów indeksujących i usług Google. 		Tak
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google otrzymało z Twojej usługi realizacji zamówień błąd HTTP 5xx.

Upewnij się, że adres URL punktu końcowego jest stabilny, poprawny i publicznie dostępny, a usługa jest uruchomiona. 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 uszkodzona, że przetwarzanie zostało przerwane.

Użyj walidatora JSON, aby sprawdzić, czy odpowiedź jest zgodna ze schematami intencji. 		Tak
EXECUTION_GAL_BAD_3P_RESPONSE Nie udało się połączyć kont 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, o które aplikacja prosi podczas uwierzytelniania 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 agentUserId mapowanie 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.

Zadbaj o to, aby tokeny były nadal ważne i zsynchronizowane, odpowiednio reaguj na zmiany stanu konta i wymagaj od użytkowników ponownego połączenia konta, jeśli tokeny zostaną unieważnione. 		Tak
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 odłączone przez usługę innej firmy.

Sprawdź, dlaczego użytkownik został odłączony (np. z powodu resetowania ustawień bezpieczeństwa). Upewnij się, że serwer OAuth partnera prawidłowo odpowiada na żądania refresh_token Google dotyczące bezproblemowego wydawania nowych tokenów dostępu. 		Tak
EXECUTION_INVALID_JSON Nie udało się przeanalizować przez Google ł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 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 Cloud Logging, aby sprawdzić logi usługi inteligentnego domu.
INVALID_JSON Struktura odpowiedzi jest nieprawidłowa (np. brakuje wymaganych pól).

Sprawdź poprawność odpowiedzi na podstawie schematów JSON intencji. 		Tak
MALFORMED_JSON Struktura JSON jest uszkodzona (np. nie ma zamkniętych ciągów znaków lub obiektów).

Sprawdź, czy usługa realizująca zamówienie używa standardowej biblioteki JSON do serializacji odpowiedzi. 		Tak
NOT_IMPLEMENTED Żądany zamiar lub cecha nie zostały zaimplementowane przez partnera.

W odpowiedzi SYNC uwzględniaj tylko te cechy, które zostały w pełni wdrożone. 		Tak
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 Zwrócony ciąg znaków errorCode nie znajduje się na liście obsługiwanych ciągów znaków Google.

Map your internal errors to the Official Error List. 		Tak
PARTNER_RESPONSE_INVALID_PAYLOAD Pole payload w odpowiedzi nie jest prawidłowym obiektem JSON.

Sprawdź strukturę główną odpowiedzi dotyczącej 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 znaków stanu. 		Tak
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Odpowiedź nie zawierała wyników dla wszystkich żądanych poleceń/urządzeń.

Sprawdź strukturę odpowiedzi w dokumentacji 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 w żądaniu 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 wszystkie znaczniki ID podane 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 zawierającym identyfikatory, stan i opcjonalne stany. 		Tak
REQUEST_ID_NOT_FOUND Nie udało nam się znaleźć wewnętrznego identyfikatora śledzenia żądania.

Zwykle jest to błąd wewnętrzny platformy. Obserwuj nagłe wzrosty 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 regionalne opóźnienia sieci. 		Tak
RESPONSE_UNAVAILABLE Nie otrzymaliśmy odpowiedzi z adresu URL realizacji zamówienia 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 dotyczące wewnętrznych limitów czasu usługi między chmurą a hubami urządzeń. 		Tak

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.

W 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 dziennika lub wpisach niestandardowych.

Wysyłanie zapytań do logów Cloud

Aby utworzyć filtry własne, możesz użyć przycisków zapytań.

Tworzenie zapytań dotyczących 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 sekcji 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:

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

Więcej przykładów skutecznego wyszukiwania w logach znajdziesz w bibliotece zapytań.

Testowanie poprawek

Po zidentyfikowaniu błędów i zastosowaniu aktualizacji w celu ich naprawienia zalecamy dokładne przetestowanie poprawek 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 działaniu inteligentnego domu. Więcej informacji o debugowaniu znajdziesz w naszych codelabach:

Wstecz
Cloud Logging dla sprawy