Google Home Vitals (Cloud)

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

Panel składa się z 3 sekcji, z których każda obejmuje kluczową część wpływającą na jakość ogólnej integracji.

1. Dane Google dotyczące partnera – mierzą kondycję połączeń z Google z Twoim backendem w chmurze.

2. Kondycja systemu – dane partnera dotyczące Google – mierzą kondycję połączeń z Twojego systemu z Google.

3. Kondycja 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 spełniają wartości docelowych, są wyróżniane na czerwono, co wskazuje na problem, który może mieć wpływ na wygodę użytkowników. Poniższe informacje zawierają szczegóły dotyczące każdego celu i wyjaśniają, dlaczego jest on ważny dla użytkowników.

Jeśli po kliknięciu poniższego przycisku nie przejdziesz bezpośrednio do panelu, możesz go otworzyć, klikając kolejno Przegląd > Panele , a następnie na liście Moje panele wybierając Google Home Vitals Dashboard (Cloud).

Otwórz Panel

Dane Google dotyczące partnera

Dane Współczynnik powodzenia zapytań/wykonywania >= 99,5% mierzą, jak często polecenia użytkowników są prawidłowo wykonywane.Pomaga to uniknąć odpowiedzi Asystenta, takich jak „Nie mogę się połączyć z urządzeniem”, lub nieprawidłowego potwierdzania polecenia, które nie zostało jeszcze wykonane.

Co oznacza „powodzenie”?

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 w typowych kodach błędów platformy , które są oznaczone jako Wymagające działania partnera, są uznawane za "niepowodzenia" podczas obliczania współczynników powodzenia ZAPYTANIA i WYKONANIA. Dodatkowo błędy znalezione w sekcji Błędy i wyjątki są również „niepowodzeniami”, z tymi wyjątkami:

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 zbyt długo czekać, np. kilka sekund na wyłączenie światła.

Dane dotyczące czasu oczekiwania

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

Aby zapewnić dokładność techniczną, Google mierzy czas oczekiwania inaczej w przypadku sprawdzania stanu niż w przypadku poleceń urządzenia.

1. Czas oczekiwania na ZAPYTANIE (interrogative)

Mierzy czas podróży w obie strony Cloud-to-cloud, gdy Google prosi o bieżący stan urządzenia.

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

2. Czas oczekiwania na WYKONANIE (action)

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

• Początek: Google wysyła żądanie action.devices.EXECUTE na adres URL realizacji.
• Okres pomiaru: czas potrzebny Twojej chmurze na odebranie polecenia i zwrócenie odpowiedzi z potwierdzeniem.
• Koniec: Google otrzymuje odpowiedź ze stanem SUCCESS, PENDING lub OFFLINE.
• Zakres techniczny: te dane mierzą czas „potwierdzenia odpowiedzi” między chmurą Google a Twoją chmurą. Nie mierzą czasu potrzebnego sprzętowi (np. żarówce) na zmianę stanu fizycznego, ponieważ często wiąże się to z czasem oczekiwania w lokalnej sieci kratowej poza ścieżką między chmurami.

Podział czasu oczekiwania na WYKONANIE/ZAPYTANIE

Podczas analizowania sygnatur czasowych czasu oczekiwania na EXECUTE lub QUERY łączny czas podróży w obie strony można podzielić na te kolejne etapy:

Ponieważ ten podział porównuje sygnatury czasowe po stronie Google i partnera, serwery partnera muszą być zsynchronizowane z protokołem NTP (Network Time Protocol). Nawet niewielkie odchylenie zegara (50–100 ms) spowoduje zniekształcenie obliczonych czasów przesyłu (t2 - t1 i t4 - t3), co może prowadzić do logicznie niemożliwych danych, takich jak ujemne czasy oczekiwania na przesył.

[t1] Wysłano żądanie (Google Outbound): Google inicjuje żądanie intencji. Ponieważ t1 nie jest bezpośrednio widoczny, jest obliczany w przybliżeniu przez odjęcie łącznego czasu oczekiwania od ostatecznej sygnatury czasowej przychodzącej.

Przesył w sieci (t1 do t2): szacowany czas przesyłu w sieci i czas oczekiwania w kolejce przed dotarciem do punktu końcowego realizacji.

[t2] Odebrano żądanie (Partner Ingress): dokładna sygnatura czasowa, gdy żądanie dociera do bramy API lub serwera wejściowego w Twoim środowisku.

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

[t3] Wysłano odpowiedź (Partner Egress): sygnatura czasowa, gdy Twoja usługa wysyła odpowiedź realizacji z powrotem do Google.

Przesył zwrotny (t3 do t4): czas routingu w sieci zwrotnej i czas zakończenia połączenia z powrotem do Google.

[t4] Żądanie zakończone (Google Inbound): Google otrzymuje i przetwarza ostateczną odpowiedź. Ta sygnatura czasowa jest wyraźnie rejestrowana w Twoich Google Cloud logach jako receiveTimestamp.

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

Opcje skracania czasu oczekiwania

Zalecenia dotyczące architektury routingu geograficznego

Jeśli implementacja protokołu Anycast IP nie jest możliwa, zalecamy te opłacalne alternatywy, aby zapewnić, że użytkownicy będą obsługiwani 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 usług w chmurze).

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

   • Zaleta: zapewnia wydajność protokołu Anycast przy znacznie niższym stopniu złożoności konfiguracji i kosztach.

2. DNS z uwzględnieniem lokalizacji geograficznej (GeoDNS)

   • Jak to działa: skonfiguruj dostawcę DNS tak, aby rozpoznawał adres URL realizacji na różne adresy IP na podstawie lokalizacji geograficznej zapytania DNS.

   • Implementacja: 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, UE lub Azji) rozpoznają Twoją domenę, otrzymają adres IP centrum danych w tym konkretnym regionie.

Strategie optymalizacji na poziomie aplikacji

Oprócz routingu na poziomie infrastruktury możesz wdrożyć te strategie na poziomie aplikacji, aby skrócić czas oczekiwania na przetwarzanie żą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 na Twój globalny adres URL.

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

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

   Zaleta: skraca czas „uzgadniania TCP”, który często jest największym czynnikiem wpływającym na czas oczekiwania 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.

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

Kondycja systemu – dane partnera dotyczące Google

Utrzymywanie współczynnika powodzenia >= 99,5% pomaga zapewnić, że stany urządzeń są prawidłowe w Google Home, urządzenia są dodawane i usuwane, automatyzacje są uruchamiane, a zdarzenia z historii pojawiają się na karcie Aktywność w Google Home app (GHA).

Współczynnik powodzenia jest obliczany na podstawie kodów odpowiedzi HTTP zwracanych przez Google, gdy Twoja chmura wysyła aktualizacje stanu. Aby partnerzy nie byli karani za problemy z infrastrukturą po stronie Google, dane te wykluczają błędy wewnętrzne Google z liczby niepowodzeń. Wywołania API uwzględnione w obliczeniach znajdziesz w dokumentacji HomeGraph API.

Co oznacza „powodzenie”?

2xx (powodzenie): aktualizacja stanu została pomyślnie odebrana i przetworzona przez Home Graph.

Co oznacza „niepowodzenie”?

4xx (błąd partnera) oznaczają niepowodzenia i wskazują na 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. Typowe przyczyny to nieprawidłowy format 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 plikiem JSON (nie zawiera nieprawidłowej struktury ani wartości null w polach ciągu znaków) oraz że wartość agentUserId jest zgodna z wartością z odpowiedzi SYNC.

Błąd 404 (nie znaleziono)

Przyczyna: nie znaleziono wartości deviceId ani agentUserId w HomeGraph (nie zsynchronizowano jeszcze, odłączono lub wystąpiła niezgodność identyfikatorów).

Rozwiązanie:

1. Upewnij się, że wartość agentUserId jest zgodna z wartością podaną w odpowiedzi SYNC.
2. Użyj Home Graph SYNC API aby sprawdzić, czy błąd 404 (nie znaleziono) jest spowodowany brakiem urządzenia lub użytkownika w HomeGraph.
3. Po dodaniu, usunięciu, zmianie nazwy lub zaktualizowaniu urządzenia lub konta uruchom requestSync, aby stan był aktualny.
4. Prawidłowo obsługuj DISCONNECT intencje aby zatrzymać raportowanie nieaktualnych urządzeń. Po otrzymaniu intencji DISCONNECT, Twoja usługa w chmurze powinna przestać publikować zmiany w Google za pomocą funkcji Request Sync i Report State.

429 Zasób wyczerpany

Przyczyna: Twoja integracja przekroczyła przydzielony limit.

Rozwiązanie: instrukcje dotyczące zarządzania limitami znajdziesz w sekcji „Krok 2a: debugowanie problemów z limitami” w panelu. Więcej informacji znajdziesz też w artykule Limity i ograniczenia Smart Home.

Kondycja urządzenia – dokładność stanu

Spełnienie lub przekroczenie wartości Dokładność stanu >= 99,5% pomaga zapewnić, że użytkownicy będą widzieć prawidłowe wyniki, gdy wyświetlają stany urządzeń lub korzystają z funkcji AI, takich jak Zapytaj Home. Jeśli dokładność stanu jest niska, automatyzacje mogą się nie uruchamiać, a wpisy w historii mogą się nie pojawiać na karcie Aktywność w aplikacji GHA's we właściwym czasie. Więcej informacji znajdziesz w artykule Report State. Uwaga: cel Dokładność stanu musi być spełniony we WSZYSTKICH obsługiwanych cechach.

1. Składniki dokładności

Dane są wyprowadzane z „próbek”, w których Google może zweryfikować zgłoszony stan na podstawie znanego wyniku intencji. Aby zapewnić dokładność techniczną, dokładność jest oceniana na 2 odrębnych ścieżkach:

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

2. Dane panelu (obliczane co godzinę)

Panel oblicza dokładność na podstawie 1-godzinnego interwału. Aby zapewnić wiarygodność statystyczną i uniknąć karania integracji za szumy o niskim sygnale, Google wymusza minimalny próg natężenia ruchu. Jeśli w przypadku konkretnej cechy i urządzenia w 5-dniowym okresie kroczącym zgromadzi się mniej niż 100 próbek, jego dokładność jest uznawana za statystycznie nieistotną i ustawiana na N/A.

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

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

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

• Dokładność zapytania % = (Godzinowe dokładne próbki zapytania) / (Godzinowe próbki zapytania ogółem)
• Dokładność wykonania % = (Godzinowe dokładne próbki wykonania) / (Godzinowe próbki wykonania ogółem)

Wynik dokładności cechy (obliczany na podstawie cechy) = SUMA(Dokładne próbki zapytania + Dokładne próbki wykonania) / SUMA(Próbki zapytania ogółem + Próbki wykonania ogółem)

Ponieważ Wynik jakości ocenia ścisłe minimum wydajności w Twoim ekosystemie, każda obsługiwana i kwalifikująca się cecha musi indywidualnie spełniać cel Dokładność stanu >= 99,5% (nie jest to średnia z cech).

Ten widok uniemożliwia urządzeniom o dużej liczbie próbek i doskonałej dokładności maskowanie problemów z dokładnością na urządzeniach o mniejszej liczbie próbek. Partnerzy, którzy obawiają się, że niewykorzystane cechy obniżą ich wynik, mogą mieć pewność, że rzadko używana cecha jest automatycznie chroniona przez minimalny próg natężenia ruchu i nie będzie uwzględniana w najniższym wyniku typu i cechy, chyba że spełni wymagany próg próbek.

3. Poprawianie kondycji urządzenia i dokładności stanu

Rozbieżności występują, gdy stan przechowywany w Home Graph nie jest zgodny z wynikami 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ę w odpowiedzi na ZAPYTANIE i w żądaniu Report State dla tego samego urządzenia.

Rozwiązanie: upewnij się, że struktura danych jest identyczna na obu ścieżkach. Jeśli cecha jest uwzględniona w SYNC, jej odpowiednie pola muszą być obecne i spójne zarówno w raportach proaktywnych, jak i w 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 na ZAPYTANIE a ostatnią wartością Report State.

Rozwiązanie: upewnij się, że funkcja Report State jest uruchamiana za każdym razem, gdy zmienia się stan urządzenia, oraz że zarówno Report State, jak i ZAPYTANIE zawsze podają 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: w przypadku błędu DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE partner wykonał polecenie, ale nie zgłosił zaktualizowanego stanu urządzenia do Google.

Rozwiązanie: po wykonaniu polecenia zawsze wysyłaj aktualizację Report State, 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 żadnego Report State dla tego urządzenia (stan jest pusty, a zgłoszona sygnatura czasowa jest w epoce), mimo że wyniki ZAPYTANIA podają bieżący stan. Oznacza to, że aktualizacje stanu nie są uruchamiane, nie docierają do HomeGraph lub urządzenie nie zgłasza prawidłowo przejść w stanie połączenia lub stanu operacyjnego.

Rozwiązanie: upewnij się, że funkcja Report State jest uruchamiana i wysyłana prawidłowo w przypadku wszystkich zmian stanu. Sprawdź, czy logika backendu prawidłowo obsługuje aktualizacje stanu, potwierdza dostarczenie do Google HomeGraph i zapewnia, że urządzenie stale synchronizuje swój stan, aby interfejs użytkownika i silnik automatyzacji były dokładne.