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 ma 3 sekcje, z których każda obejmuje kluczową część wpływającą na jakość ogólnej integracji.

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

2. Stan systemu – dane partnera dotyczące Google – mierzą stan połączeń z Twojego systemu z Google.

3. Stan urządzenia – dokładność stanu – mierzą 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 ten przycisk nie przekierowuje bezpośrednio do panelu, możesz go otworzyć, klikając kolejno Przegląd > Panele , a następnie na liście Moje panele wybierając panel Google Home Vitals (chmura).

Otwórz Panel

Dane Google dotyczące partnera

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

Dane Współczynnik sukcesu synchronizacji >= 99,5% mierzą, jak często żądania synchronizacji są wykonywane 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 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 sukcesu QUERY, EXECUTE i SYNC. Dodatkowo błędy znalezione w Błędy i wyjątki są również "niepowodzeniami", z tymi wyjątkami:

Parzystość stanu odpowiedzi wykonania

Gdy w odpowiedzi EXECUTE zwracasz stan SUCCESS, ładunek odpowiedzi states 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 złożonych cech spowoduje, że platforma Google Home nie będzie mogła przeanalizować wyniku wykonania, rejestrując go jako niepowodzenie AGENT_ISSUE lub INVALID_RESPONSE, co obniży współczynnik sukcesu zapytań i wykonywania.

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 (interaktywne)

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 Twój 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 odbiera i potwierdza ostateczny ładunek odpowiedzi z Twojej usługi.

2. Czas oczekiwania na wykonanie (działanie)

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

• Początek: Google wysyła żądanie action.devices.EXECUTE na Twój adres URL realizacji.
• Okres pomiaru: czas potrzebny Twojej chmurze na odebranie polecenia i zwrócenie odpowiedzi z potwierdzeniem.
• Koniec: Google odbiera 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 typu mesh poza ścieżką między chmurami.

Podział czasu oczekiwania na wykonanie/zapytanie

Podczas analizowania sygnatur czasowych czasu oczekiwania na EXECUTE lub QUERY łączny czas błądzenia można podzielić na te kolejne etapy:

Ponieważ to zestawienie 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 (wychodzące z Google): Google inicjuje żądanie intencji. Ponieważ t1 nie jest bezpośrednio widoczny, jest obliczany w przybliżeniu przez odjęcie łącznego czasu oczekiwania od końcowej 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 (przychodzące do partnera): dokładna sygnatura czasowa, gdy żądanie dociera do bramy API lub serwera przychodzącego w Twoim środowisku.

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

[t3] Wysłano odpowiedź (ruch wychodzący od partnera): 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 zakończenia połączenia z powrotem do Google.

[t4] Żądanie zakończone (przychodzące do Google): Google odbiera 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żywaj 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 jeden 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 poziomie 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ł Twój adres URL realizacji na podstawie położenia geograficznego zapytania DNS.

   • Implementacja: upewnij się, że dostawca DNS jest zoptymalizowany pod kątem punktów ruchu wychodzącego Google. Gdy regionalne usługi realizacji Google (np. w Stanach Zjednoczonych, UE lub Azji) rozpoznają Twoją domenę, otrzymają adres IP centrum danych w tym 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 „Trampolina”

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

   1. Google wysyła żądanie na Twój globalny adres URL.

   2. Żądanie odbiera regionalny serwer proxy (np. 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.

Stan systemu – dane partnera dotyczące Google

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

Współczynnik sukcesu 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 „sukces”?

2xx (sukces): aktualizacja stanu została 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 (bez nieprawidłowej struktury lub wartości null w polach ciągu znaków) i że wartość agentUserId jest zgodna z wartością z odpowiedzi SYNC.

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 wywołaj requestSync, aby stan był aktualny.
4. Prawidłowo obsługuj DISCONNECT intencje aby przestać zgłaszać nieaktualne urządzenia. Po otrzymaniu intencji DISCONNECT Twoja usługa w chmurze powinna przestać publikować zmiany w Google za pomocą 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.

Stan urządzenia – dokładność stanu

Spełnienie lub przekroczenie dokładności 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 Zgłaszanie stanu. Uwaga: cel dokładności 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ć precyzję techniczną, dokładność jest oceniana na 2 odrębne sposoby:

• Dokładność na podstawie QUERY: weryfikowana, gdy użytkownik lub system aktywnie sprawdza bieżący stan urządzenia.
• Dokładność na podstawie EXECUTE: weryfikowana przez ocenę stanu urządzenia po poleceniu zgłoszonego 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 określonej kombinacji cechy i urządzenia w 5-dniowym okresie kroczącym zgromadzi się mniej niż 100 próbek, jej 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 % = (godzinowa liczba dokładnych próbek zapytania) / (godzinowa łączna liczba próbek zapytania)
• Dokładność wykonania % = (godzinowa liczba dokładnych próbek wykonania) / (godzinowa łączna liczba próbek wykonania)

Wynik dokładności cechy (obliczany na podstawie cechy) = SUMA(liczba dokładnych próbek zapytania + liczba dokładnych próbek wykonania) / SUMA(łączna liczba próbek zapytania + łączna liczba próbek wykonania)

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ści stanu >= 99,5% (nie jest to średnia z cech).

Ten widok uniemożliwia maskowanie problemów z dokładnością na urządzeniach o mniejszym natężeniu ruchu przez urządzenia o dużym natężeniu ruchu i doskonałej dokładności. Partnerzy, którzy obawiają się, że niedostatecznie wykorzystywane cechy obniżają ich wynik, mogą mieć pewność, że rzadko używana cecha jest automatycznie chroniona przez sprawdzanie minimalnego natężenia ruchu i nie będzie uwzględniana w najniższym wyniku typu i cechy, dopóki nie osiągnie wymaganego progu próbek.

3. Poprawianie stanu 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ę między odpowiedzią QUERY a żądaniem 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 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ą 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 Report State dla tego urządzenia (stan jest pusty, a zgłoszona sygnatura czasowa jest w epoce), mimo że wyniki QUERY podają bieżący stan. Oznacza to, że aktualizacje stanu nie są wyzwalane, nie docierają do HomeGraph lub urządzenie nie zgłasza prawidłowo przejść w stanie połączenia lub operacyjnym.

Rozwiązanie: upewnij się, że funkcja Report State jest wywoływana 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 konsekwentnie synchronizuje swój stan, aby interfejs użytkownika i mechanizm automatyzacji były dokładne.