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 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 do Twojego backendu w chmurze.

2. Stan systemu – dane partnera dotyczące Google – mierzą 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 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 kliknięcie poniższego przycisku nie spowoduje bezpośredniego przejścia 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 (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 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 Wymagane działanie partnera są uznawane za "niepowodzenia" podczas obliczania współczynników powodzenia zapytań i wykonywania. Dodatkowo błędy znalezione w sekcji Błędy i wyjątki są również "niepowodzeniami", z wyjątkiem tych:

Wskaźnik Czas oczekiwania na zapytanie/wykonanie (p90) <= 1000 ms mierzy czas oczekiwania na żądane działanie i pomaga 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 poziomie 90. percentyla (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 odbiera i potwierdza końcowy ładunek odpowiedzi 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 typu mesh poza ścieżką między chmurami.

Opcje skracania czasu oczekiwania

Zalecenia dotyczące architektury w przypadku routingu geograficznego

Jeśli wdrożenie protokołu Anycast IP nie jest możliwe, zalecamy te ekonomiczne 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 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 w dobrym stanie.

   • 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ł adres URL realizacji 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, 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 podczas przetwarzania żądań.

1. Metoda proxy „Trampolina”

   Jeśli musisz utrzymywać główne centrum danych, używaj regionalnych lekkich 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. lekka funkcja Nginx lub Lambda).

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

   Zaleta: skraca to 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 w tokenie dostępu

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

   Wdrożenie: zakoduj identyfikator regionu w tokenie access_token wydanym Google. Gdy Google wyśle żą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 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 interfejsu API uwzględnione w obliczeniach znajdziesz w dokumentacji interfejsu 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 (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 lub agentUserId w HomeGraph (jeszcze nie zsynchronizowano, już odłączono lub występuje niezgodność identyfikatorów).

Rozwiązanie:

1. Upewnij się, że wartość agentUserId jest zgodna z wartością podaną w odpowiedzi SYNC.
2. Użyj interfejsu 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, 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.

Stan 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 opartych na AI, takich jak Zapytaj Home. Jeśli dokładność stanu jest niska, automatyzacje mogą się nie uruchamiać, a wpisy w historii mogą nie pojawiać się na karcie Aktywność w aplikacji GHA we właściwym czasie. Więcej informacji znajdziesz w artykule Report State.

Panel jakości śledzi te dane co godzinę za pomocą 2 różnych danych: Ogólna dokładność i Najniższa kombinacja typu/cechy.

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.

2. Dane panelu (obliczenia godzinowe)

Panel oblicza dokładność na podstawie 1-godzinnego interwału. Jeśli w ciągu godziny łączna liczba próbek jest mniejsza niż 100 (S_Total < 100), dokładność dla tej godziny jest ustawiana na N/D.

Widok 1. Ogólna dokładność (średnia globalna)

Reprezentuje łączną dokładność integracji we wszystkich typach urządzeń i cechach. Jest to średnia ważona stanu całego ekosystemu.

• Obliczenia: łączna dokładność stanu na wszystkich urządzeniach / łączna liczba stanów na wszystkich urządzeniach.

Widok 2. Najniższa kombinacja typu/cechy

Identyfikuje najbardziej zawodną kategorię w Twojej integracji. Zapobiega to ukrywaniu urządzeń o niskiej jakości przez urządzenia o dużej liczbie i wysokiej jakości. Jeśli na przykład masz dużą liczbę świateł o dokładności stanu powyżej 99,5%, ale małą liczbę przełączników o niskiej dokładności stanu, ta funkcja wyróżni potrzebę poprawy w przypadku przełączników, które mogą zostać pominięte w wartości średniej.

• Obliczenia: minimum dokładności stanu / łączna liczba stanów dla wszystkich kombinacji cech i urządzeń.

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 w 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 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 uruchamiana 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 żadnego raportu 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. Wskazuje 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 mechanizm automatyzacji były dokładne.