Google Home Vitals (Cloud)

Ten zestaw paneli i alertów pomaga proaktywnie utrzymywać wysoką jakość integracji z ekosystemem Google Home. Google dokłada wszelkich starań, aby wspierać partnerów w tworzeniu wysokiej jakości ekosystemu dla wszystkich klientów.

Panel składa się z 3 sekcji, z których każda obejmuje kluczowy element wpływający na jakość całej integracji.

1. Wskaźniki Google do partnera – mierzą stan połączeń z Google do backendu w chmurze.

2. Stan systemu – dane dotyczące połączeń między partnerem a Google – mierzy stan połączeń z Twojego systemu do Google.

3. Stan urządzenia – dokładność stanu – mierzy dokładność stanów przechowywanych w systemach Google, które są używane do obsługi zapytań użytkowników.

Gdy dane nie osiągają wartości docelowych, są wyróżnione na czerwono, co oznacza problem, który może mieć wpływ na wrażenia użytkownika. Poniżej znajdziesz szczegółowe informacje o każdym celu i o tym, dlaczego jest on ważny dla użytkowników.

Jeśli przycisk poniżej nie przeniesie Cię bezpośrednio do panelu, możesz go otworzyć, wybierając stronę Przegląd, a następnie Panele i Panel Google Home Vitals (Cloud) na liście Moje panele.

Otwórz Panel

Dane dotyczące połączenia Google – partner

Dane Wskaźnik sukcesu zapytania/wykonania >= 99,5% mierzą, jak często polecenia użytkowników są prawidłowo wykonywane, co pomaga uniknąć odpowiedzi Asystenta takich jak „Nie mogę połączyć się z urządzeniem” lub nieprawidłowego potwierdzenia polecenia, które nie zostało jeszcze wykonane.

Dane Wskaźnik sukcesu synchronizacji >= 99,5% mierzą, jak często żądania synchronizacji są realizowane prawidłowo, co zapewnia, że urządzenia wyświetlane w Google Home są zsynchronizowane z urządzeniami połączonymi z Twoją infrastrukturą w chmurze.

Co oznacza „Sukces”?

Transakcja jest oznaczana jako udana, jeśli platforma Google Home otrzyma prawidłową odpowiedź wskazującą, że zamierzone działanie zostało wykonane lub żądany stan został pobrany.

Odpowiedzi, które zawierają wyjątki nieblokujące (np. stan SUCCESS z wyjątkiem lowBattery), są liczone jako udane transakcje. Polecenie dotarło do urządzenia, a intencja została spełniona pomimo ostrzeżenia.

Co oznacza „Niepowodzenie”?

Błędy znalezione na stronie Typowe kody błędów platformy, które są oznaczone jako Wymagające działania partnera, są uznawane za „niepowodzenia” podczas obliczania wskaźników sukcesu poleceń QUERY, EXECUTE i SYNC. Dodatkowo błędy znalezione na stronie Błędy i wyjątki są również „błędami”, z tymi wyjątkami:

Zgodność stanu odpowiedzi na wykonanie

Gdy zwracasz stan SUCCESS w odpowiedzi EXECUTE, obiekt states w danych odpowiedzi musi zawierać wszystkie aktywne i zaktualizowane pola stanu zdefiniowane przez cechy, które wykonujesz. Pominięcie wymaganych pól stanu lub zwrócenie pustego obiektu states w przypadku cech złożonych spowoduje, że platforma Google Home nie będzie mogła przeanalizować wyniku wykonania i zarejestruje go jako błąd AGENT_ISSUE lub INVALID_RESPONSE, co obniży wskaźnik sukcesu zapytań i wykonań.

Dane Czas oczekiwania na zapytanie/wykonanie (p90) <= 1000 ms mierzą czas oczekiwania na żądane działanie i pomagają zapewnić, że użytkownicy nie będą musieli czekać zbyt długo, na przykład kilka sekund na wyłączenie światła.

Wskaźniki czasu oczekiwania

Czas oczekiwania jest kluczowym wskaźnikiem tego, jak szybko integracja reaguje na działania użytkownika. Panel śledzi czas oczekiwania na poziomie 90. percentyla (P90), który odzwierciedla wrażenia „najwolniejszych” użytkowników (np. P90 wynoszący 800 ms oznacza, że 90% żądań jest potwierdzanych w ciągu maksymalnie 800 ms).

Aby zapewnić dokładność techniczną, Google mierzy opóźnienia inaczej w przypadku sprawdzania stanu, a inaczej w przypadku poleceń urządzenia.

1. Czas oczekiwania na odpowiedź na ZAPYTANIE (pytanie)

Mierzy czas błądzenia Cloud-to-cloud, gdy Google pyta o bieżący stan urządzenia.

• Początek: Google wysyła żądanie action.devices.QUERY na adres URL realizacji.
• Okno pomiaru: czas potrzebny na odebranie, przetworzenie i przesłanie pełnej odpowiedzi HTTP z powrotem do Google.
• Koniec: Google otrzymuje i potwierdza ostateczny ładunek odpowiedzi z Twojej usługi.

2. Czas oczekiwania na wykonanie (działanie)

Mierzy czas potwierdzenia polecenia, gdy Google wysyła do urządzenia żądanie sterowania.

• Początek: Google wysyła żądanie action.devices.EXECUTE na adres URL realizacji.
• Okno pomiaru: czas potrzebny na odebranie polecenia przez chmurę i zwrócenie odpowiedzi z potwierdzeniem.
• Koniec: Google otrzymuje odpowiedź ze stanem SUCCESS, PENDING lub OFFLINE.
• Zakres techniczny: ten wskaźnik mierzy czas „potwierdzenia odpowiedzi” między chmurą Google a Twoją chmurą. Nie mierzy czasu potrzebnego na zmianę stanu fizycznego sprzętu (np. żarówki), ponieważ często wiąże się to z opóźnieniem lokalnej sieci typu mesh poza ścieżką między chmurami.

Zestawienie osi czasu oczekiwania na EXECUTE/QUERY

Podczas analizowania sygnatur czasowych opóźnienia EXECUTE lub QUERY łączny czas błądzenia można podzielić na następujące sekwencje:

Ponieważ to zestawienie porównuje sygnatury czasowe po stronie Google i po stronie partnera, serwery partnera muszą być zsynchronizowane z protokołem NTP (Network Time Protocol). Nawet niewielkie przesunięcie zegara (50–100 ms) zniekształci obliczone czasy przewozu (t2 - t1 i t4 - t3), co może prowadzić do logicznie niemożliwych danych, takich jak ujemne opóźnienia przewozu.

[t1] Wysłano prośbę (Google Outbound): Google inicjuje prośbę o zamiar. Ponieważ wartość t1 nie jest bezpośrednio widoczna, jest obliczana w przybliżeniu przez odjęcie łącznego czasu oczekiwania od końcowej sygnatury czasowej ruchu przychodzącego.

Network Transit (t1 to t2) (Przesyłanie przez sieć ( do )):szacowany czas przesyłania przez sieć i czas oczekiwania w kolejce przed dotarciem do punktu końcowego realizacji.

[t2] Otrzymano żądanie (ruch przychodzący partnera): dokładna sygnatura czasowa, kiedy żądanie dotarło do bramy interfejsu API lub serwera ruchu przychodzącego w Twoim środowisku.

Przetwarzanie przez partnera (t2 do t3): czas oczekiwania na wykonanie, routing i obsługę urządzenia w Twoim środowisku chmury.

[t3] Odpowiedź wysłana (ruch wychodzący partnera): sygnatura czasowa, kiedy usługa wysyła odpowiedź dotyczącą realizacji z powrotem do Google.

Powrotny transport (t3 do t4): czas potrzebny na powrotne przekierowanie sieci i zakończenie połączenia z Google.

[t4] Żądanie sfinalizowane (przychodzące do Google): Google otrzymuje i przetwarza ostateczną odpowiedź. Ta sygnatura czasowa jest wyraźnie zapisana w logach Google Cloud jako receiveTimestamp.

Aby zilustrować, jak te dane są ze sobą powiązane, rozważmy przykładowe żądanie EXECUTE z łącznym zarejestrowanym opóźnieniem (latencyMsec) wynoszącym 1700 ms i Google Cloud receiveTimestamp (t4) wynoszącym 2026-05-25T15:25:00.550Z.

Opcje skracania czasu oczekiwania

Zalecenia dotyczące architektury routingu geograficznego

Jeśli wdrożenie adresu IP Anycast nie jest możliwe, zalecamy te ekonomiczne alternatywy, które zapewnią użytkownikom obsługę przez najbliższe regionalne centrum danych.

1. Globalne równoważenie obciążenia (GLB)

   Zamiast routingu statycznego użyj globalnego systemu równoważenia obciążenia aplikacji (dostępnego u większości głównych dostawców chmury).

   • Jak to działa: konfigurujesz pojedynczy globalny punkt wejścia (URL), który znajduje się na brzegu sieci. System równoważenia obciążenia automatycznie wykrywa pochodzenie geograficzne żądania z klastrów realizacji Google i kieruje ruch do najbliższego regionalnego backendu o prawidłowym stanie.

   • Korzyść: zapewnia to wydajność Anycast przy znacznie mniejszej złożoności konfiguracji i niższych kosztach.

2. DNS uwzględniający geolokalizację (GeoDNS)

   • Jak to działa: skonfiguruj dostawcę DNS, aby rozpoznawał adres URL realizacji na różne adresy IP na podstawie położenia geograficznego zapytania DNS.

   • Wdrożenie: upewnij się, że dostawca DNS jest zoptymalizowany pod kątem punktów wyjścia Google. Gdy regionalne usługi realizacji Google (np. w Stanach Zjednoczonych, Unii Europejskiej lub Azji) rozpoznają Twoją domenę, otrzymają adres IP centrum danych w tym konkretnym regionie.

Strategie optymalizacji na poziomie warstwy aplikacji

Oprócz routingu na poziomie infrastruktury możesz wdrożyć te strategie na warstwie aplikacji, aby zmniejszyć opóźnienia w przetwarzaniu żądań.

1. Metoda proxy „Trampoline”

   Jeśli musisz utrzymywać główne centrum danych, użyj regionalnych lekkich serwerów proxy (Trampolines) do obsługi początkowego uzgadniania.

   1. Google wysyła żądanie do globalnego adresu URL.

   2. Żądanie odbiera regionalny serwer proxy (np. lekki serwer Nginx lub funkcja Lambda).

   3. Serwer proxy przekazuje ładunek przez wewnętrzną, szybką sieć szkieletową do głównej bazy danych.

   Korzyść: skraca to czas „uzgadniania TCP”, który często jest największym czynnikiem wpływającym na opóźnienia w przypadku żądań na duże odległości.

2. Wskazówki dotyczące regionu tokena dostępu

   Podczas procesu łączenia kont (OAuth) Twój system może zidentyfikować region domowy użytkownika.

   Wdrożenie: zakoduj identyfikator regionu w access_token wydanym Google. Gdy Google wysyła żądanie realizacji, brama może natychmiast sprawdzić token i przekierować żądanie do odpowiedniego klastra regionalnego bez konieczności wyszukiwania w bazie danych.

Stan systemu – wskaźniki dotyczące komunikacji między partnerem a Google

Utrzymanie wskaźnika sukcesu na poziomie co najmniej 99,5% pomaga zapewnić, że stany urządzeń są prawidłowe w Google Home, urządzenia są dodawane i usuwane, automatyzacje są aktywowane, a zdarzenia z historii pojawiają się na karcie Aktywność w Google Home app (GHA).

Wskaźnik sukcesu jest obliczany na podstawie kodów odpowiedzi HTTP zwracanych przez Google, gdy chmura przesyła aktualizacje stanu. Aby partnerzy nie byli karani za problemy z infrastrukturą po stronie Google, dane te nie uwzględniają błędów wewnętrznych Google w liczbie niepowodzeń. Wywołania interfejsu API uwzględnione w obliczeniach znajdziesz w dokumentacji interfejsu HomeGraph API.

Co oznacza „Sukces”?

2xx (Sukces): aktualizacja stanu została odebrana i przetworzona przez Home Graph.

Co oznacza „Niepowodzenie”?

4xx (błąd partnera) oznacza niepowodzenie i wskazuje problem z żądaniem wysłanym z Twojej chmury. Typowe kody:

400 Nieprawidłowe żądanie

Przyczyna: serwer nie mógł przetworzyć żądania z powodu nieprawidłowej składni. Najczęstsze przyczyny to nieprawidłowo sformatowany kod JSON lub użycie wartości null zamiast „” w przypadku wartości ciągu znaków.

Rozwiązanie: upewnij się, że treść żądania jest prawidłowym kodem JSON (nie ma nieprawidłowej struktury ani wartości null w polach ciągów znaków) i sprawdź, czy agentUserId odpowiada wartości z odpowiedzi SYNC.

Błąd 404 (nie znaleziono)

Przyczyna: nie znaleziono deviceId lub agentUserId w HomeGraph (jeszcze nie zsynchronizowano, już odłączono lub identyfikator jest niezgodny).

Rozwiązanie:

1. Upewnij się, że agentUserId odpowiada wartości podanej w odpowiedzi SYNC.
2. Użyj interfejsu SYNC API Home Graph, aby sprawdzić, czy błąd 404 (nie znaleziono) jest spowodowany brakiem urządzenia lub użytkownika w Home Graph.
3. Pamiętaj, aby po dodaniu, usunięciu, zmianie nazwy lub zaktualizowaniu urządzenia lub konta wywołać requestSync, aby stan był aktualny.
4. Prawidłowo obsługuj intencje DISCONNECT, aby przestać zgłaszać nieaktualne urządzenia. Po otrzymaniu intencji DISCONNECT usługa w chmurze powinna przestać publikować zmiany w Google za pomocą Request Sync i Report State.

429 Zasób wyczerpany

Przyczyna: integracja przekroczyła przydzielony limit.

Rozwiązanie: zapoznaj się z instrukcjami w sekcji „Krok 2a: debugowanie problemów z limitami” w panelu zarządzania limitami. Więcej informacji znajdziesz też w artykule o limitach dotyczących inteligentnego domu.

Stan urządzenia – dokładność stanu

Osiągnięcie lub przekroczenie wartości Dokładność stanu >= 99,5% pomaga zapewnić użytkownikom prawidłowe wyniki, gdy sprawdzają stany urządzeń lub korzystają z funkcji opartych na AI, takich jak Zapytaj Home. Jeśli dokładność stanu jest niska, automatyzacje mogą się nie uruchamiać, a wpisy historii mogą nie pojawiać się na karcie Aktywność urządzenia GHA we właściwym czasie. Więcej informacji znajdziesz w artykule Report State. Uwaga: docelowa dokładność stanu musi być osiągnięta w przypadku WSZYSTKICH obsługiwanych cech.

1. Komponenty dokładności

Dane te są uzyskiwane z „próbek”, w przypadku których Google może zweryfikować zgłoszony stan na podstawie znanego wyniku intencji. W przypadku precyzji technicznej dokładność jest oceniana na 2 różne sposoby:

• Dokładność na podstawie ZAPYTANIA: weryfikacja następuje, gdy użytkownik lub system aktywnie sprawdza bieżący stan urządzenia.
• Dokładność na podstawie polecenia EXECUTE: weryfikowana przez ocenę stanu urządzenia po poleceniu, który jest zgłaszany po żądaniu sterowania.

2. Wskaźniki panelu (obliczenia godzinowe)

Panel oblicza dokładność na podstawie 1-godzinnego interwału. Aby zapewnić wiarygodność statystyczną i uniknąć karania integracji za niski poziom sygnału, Google stosuje minimalny próg natężenia ruchu. Jeśli w przypadku konkretnej kombinacji cechy i urządzenia w ciągu 5 dni zostanie zebranych mniej niż 100 próbek, dokładność jest uznawana za nieistotną statystycznie i jest oznaczana jako nie dotyczy.

Gdy w ciągu godziny zostanie zebrana wystarczająca liczba próbek w obu ścieżkach, bazowa dokładność godzinowa dla danego stanu jest obliczana jako średnia z 2 niezależnych wartości procentowych:

Dokładność stanu godzinowego = (% dokładności zapytania + % dokładności wykonania) / 2

Każda ścieżka jest zdefiniowana w ten sposób:

• Dokładność zapytań (%) = (dokładne próbki zapytań godzinowych) / (wszystkie próbki zapytań godzinowych)
• Dokładność wykonania (%) = (dokładne próbki wykonania na godzinę) / (wszystkie próbki wykonania na godzinę)

Wynik dokładności cechy (obliczany dla każdej cechy) = SUMA(próbki z dokładnym zapytaniem + próbki z dokładnym wykonaniem) / SUMA(wszystkie próbki z zapytaniem + wszystkie próbki z wykonaniem)

Wynik jakości ocenia bezwzględne minimum wydajności w całym ekosystemie, dlatego każda obsługiwana i kwalifikująca się cecha musi indywidualnie osiągnąć docelową dokładność stanu na poziomie co najmniej 99,5% (nie jest to średnia ze wszystkich cech).

Ten widok zapobiega maskowaniu problemów z dokładnością na urządzeniach o mniejszej liczbie konwersji przez urządzenia o dużej liczbie konwersji i doskonałej dokładności. Partnerzy, którzy obawiają się, że rzadko używane cechy obniżą ich wynik, mogą być pewni, że rzadko używana cecha jest automatycznie chroniona przez kontrolę minimalnego natężenia ruchu i nie będzie uwzględniana w wyniku najniższego typu i cechy, chyba że osiągnie wymagany próg próbki.

3. Poprawa dokładności stanu urządzenia

Rozbieżności występują, gdy stan zapisany w Home Graph nie odpowiada wynikom ZAPYTANIA w czasie rzeczywistym.

Błędy „Brakujące pole”

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

Przyczyna: w przypadku błędu DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD lub DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD zestaw pól ładunku różni się między odpowiedzią QUERY a żądaniem Report State dotyczącym tego samego urządzenia.

Rozwiązanie: upewnij się, że struktura danych jest identyczna w obu ścieżkach. Jeśli cecha jest uwzględniona w SYNC, odpowiadające jej pola muszą być obecne i spójne zarówno w raportach proaktywnych, jak i zapytaniach reaktywnych.

Błędy „Niedokładne”

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

Przyczyna: w przypadku błędu DETAILED_ACCURACY_RESULT_INACCURATE występuje rozbieżność między wartością zwróconą w odpowiedzi QUERY a ostatnią wartością Report State.

Rozwiązanie: upewnij się, że funkcja Report State jest wywoływana za każdym razem, gdy zmienia się stan urządzenia, oraz że zarówno Report State, jak i QUERY zawsze podają dokładnie te same, aktualne wartości i wszystkie wymagane pola, aby zachować spójność danych.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

Przyczyna: błąd DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE oznacza, że partner wykonał polecenie, ale nie zgłosił do Google zaktualizowanego stanu urządzenia.

Rozwiązanie: po wykonaniu polecenia zawsze wysyłaj aktualizację stanu raportu, aby Home Graph otrzymał nowy stan urządzenia.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

Przyczyna: w przypadku błędu DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED nie otrzymano stanu raportu dla tego urządzenia (stan jest pusty, a zgłoszony sygnatura czasowa jest w epoce), mimo że wyniki ZAPYTANIA podają bieżący stan. Oznacza to, że aktualizacje stanu nie są wywoływane, nie docierają do HomeGraph lub urządzenie nie zgłasza zmian w stanie połączenia lub działania.

Rozwiązanie: upewnij się, że funkcja Report State jest aktywowana i wysyła informacje o wszystkich zmianach stanu. Sprawdź, czy logika backendu prawidłowo obsługuje aktualizacje stanu, potwierdza pomyślne dostarczenie do Google HomeGraph i zapewnia spójną synchronizację stanu urządzenia, aby interfejs użytkownika i mechanizm automatyzacji były dokładne.