Google Home Vitals (Cloud)

Ten zestaw paneli i alertów pomaga aktywnie utrzymywać wysoką jakość integracji 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 kluczowy element wpływający na jakość ogólnej integracji.

1. Dane Google dotyczące partnera – mierzy stan połączeń z Google do Twojego zaplecza w chmurze.

2. Stan systemu – dane partnera a dane 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óżniane na czerwono, aby wskazać problem, który może mieć wpływ na wrażenia użytkowników. Poniższe informacje zawierają szczegóły dotyczące każdego celu i wyjaśnienie, dlaczego jest on ważny dla użytkowników.

Jeśli poniższy przycisk nie przekieruje Cię bezpośrednio do panelu, możesz go otworzyć, wybierając kolejno stronę Przegląd, Panele, a następnie z listy Moje panele wybierając panel Google Home Vitals (Cloud).

Otwórz Panel

Dane od Google do partnera

Wskaźnik Odsetek prawidłowo wykonanych zapytań ≥ 99,5% mierzy, jak często polecenia użytkowników są prawidłowo wykonywane, co pomaga 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 „Sukces”?

Transakcja jest oznaczana jako zakończona, 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 i intencja została zrealizowana pomimo ostrzeżenia.

Co oznacza „niepowodzenie”?

Błędy znalezione na stronie Kody błędów na wspólnej platformie, które są oznaczone jako Wymagające działania partnera, są traktowane jako „Niepowodzenia” podczas obliczania wskaźników powodzenia ZAPYTANIA i WYKONANIA. Dodatkowo błędy znalezione na stronie Błędy i wyjątki są również „niepowodzeniami”, z wyjątkiem tych:

Wartość Opóźnienie zapytania/wykonania (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 o czasie oczekiwania

Opóźnienie to kluczowy wskaźnik tego, jak szybko integracja reaguje na działania użytkownika. Panel śledzi opóźnienie na 90 percentylu (P90), które odzwierciedla wrażenia „najwolniejszych” użytkowników (np. P90 na poziomie 800 ms oznacza, że 90% żądań jest potwierdzanych w ciągu 800 ms lub krótszym).

Google mierzy opóźnienie w przypadku sprawdzania stanu i poleceń urządzenia w inny sposób, aby zapewnić dokładność techniczną.

1. Czas oczekiwania na odpowiedź na zapytanie (interrogative)

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

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

2. Opóźnienie EXECUTE (działanie)

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

• Początek: Google wysyła action.devices.EXECUTE żądanie na adres URL realizacji.
• Okres pomiaru: czas potrzebny na odebranie polecenia przez chmurę i odesłanie 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 w lokalnej sieci typu mesh, które nie jest związane ze ścieżką chmura-chmura.

Opcje skracania czasu oczekiwania

Zalecenia architektoniczne dotyczące kierowania geograficznego

Jeśli wdrożenie adresu IP Anycast nie jest możliwe, zalecamy te ekonomiczne alternatywy, które zapewnią obsługę użytkowników 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. Równoważenie obciążenia automatycznie wykrywa geograficzne pochodzenie żądania z klastrów realizacji Google i kieruje ruch do najbliższego regionalnego, działającego prawidłowo backendu.

   • Korzyść: zapewnia wydajność technologii Anycast przy znacznie niższym poziomie złożoności konfiguracji i kosztów.

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

   • Jak to działa: skonfiguruj dostawcę DNS tak, aby rozpoznawał adres URL realizacji zamówienia na różne adresy IP w zależności od położenia geograficznego zapytania DNS.

   • Implementacja: upewnij się, że Twój dostawca DNS jest zoptymalizowany pod kątem punktów ruchu wychodzącego Google. Gdy regionalne usługi realizacji zamówień Google (np. w Stanach Zjednoczonych, UE lub Azji) rozpoznają Twoją domenę, otrzymają adres IP centrum danych w tym konkretnym regionie.

Strategie optymalizacji na warstwie aplikacji

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

1. Metoda serwera proxy „Trampoline”

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

   1. Google odwiedza Twój globalny adres URL.

   2. Żądanie jest odbierane przez serwer proxy regionalny (np. uproszczoną funkcję Nginx lub Lambda).

   3. Serwer proxy przekazuje ładunek przez wewnętrzną sieć szkieletową o dużej szybkości do podstawowej bazy danych.

   Korzyść: skraca to czas „uzgadniania TCP”, który często jest największym czynnikiem wpływającym na opóźnienie 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 określić region domowy użytkownika.

   Implementacja: zakoduj identyfikator regionu w access_token wydanym dla 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 od partnera do Google

Utrzymywanie wskaźnika sukcesu na poziomie co najmniej 99,5% pomaga zapewnić, że stany urządzeń w Google Home są prawidłowe, urządzenia są dodawane i usuwane, automatyzacje są wyzwalane, a zdarzenia historyczne 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 mieć pewność, że partnerzy nie będą karani za problemy z infrastrukturą po stronie Google, w liczbie błędów nie uwzględniamy błędów wewnętrznych Google. Wywołania interfejsu API uwzględnione w obliczeniach znajdziesz w dokumentacji HomeGraph API.

Co oznacza „Sukces”?

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

Co oznacza „niepowodzenie”?

Błędy 4xx (błędy partnera) oznaczają niepowodzenia i wskazują 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. Częste przyczyny to nieprawidłowy format JSON lub użycie wartości null zamiast „” w przypadku wartości ciągu.

Rozwiązanie: upewnij się, że treść żądania jest prawidłowym plikiem JSON (nie zawiera nieprawidłowej struktury ani wartości null w przypadku pól tekstowych) i sprawdź, czy wartość agentUserId jest zgodna z wartością z odpowiedzi SYNC.

Błąd 404 (nie znaleziono)

Przyczyna: urządzenia deviceId lub agentUserId nie znaleziono w HomeGraph (nie zostało jeszcze zsynchronizowane, zostało już odłączone lub wystąpiła niezgodność identyfikatora).

Rozwiązanie:

1. Sprawdź, czy 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 Not Found jest spowodowany brakiem urządzenia lub użytkownika w Home Graph.
3. Pamiętaj, aby wywołać requestSync po dodaniu, usunięciu, zmianie nazwy lub zaktualizowaniu urządzenia lub konta, aby stan był aktualny.
4. Prawidłowo obsługuj intencje DISCONNECT, aby przestać raportować nieaktualne urządzenia. Po otrzymaniu DISCONNECT intencji 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: postępuj zgodnie z instrukcjami w sekcji „Krok 2a. Rozwiązywanie problemów z limitami” na panelu do zarządzania limitami. Więcej informacji znajdziesz też w artykule Limity dotyczące inteligentnego domu.

Stan urządzenia – dokładność stanu

Spełnienie lub przekroczenie dokładności stanu >= 99,5% pomaga zapewnić użytkownikom wyświetlanie prawidłowych wyników podczas sprawdzania stanów urządzeń lub korzystania 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ą się nie pojawiać we właściwym czasie na karcie Aktywność GHA. Więcej informacji znajdziesz w artykule Stan raportu.

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

1. Komponenty dokładności

Dane pochodzą z „próbek”, w przypadku których Google może zweryfikować zgłoszony stan na podstawie znanego wyniku intencji.

2. Dane w panelu (obliczane co godzinę)

Panel oblicza dokładność na podstawie godzinnego przedziału czasu. Jeśli w ciągu godziny liczba wszystkich próbek (S_Total) jest mniejsza niż 100, dokładność dla tej godziny jest ustawiana na N/A.

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

Jest to łączna dokładność integracji na wszystkich typach urządzeń i w przypadku wszystkich cech. Zawiera on ważoną średnią kondycji 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

Wskazuje to najbardziej zawodną kategorię w integracji. Zapobiega to ukrywaniu urządzeń o niskiej jakości przez urządzenia o wysokiej jakości, które generują duży ruch. 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, wskazuje to na konieczność poprawy działania przełączników, co może być niewidoczne w wartości średniej.

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

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

Rozbieżności występują, gdy stan przechowywany w Home Graph nie jest zgodny z wynikami zapytania w czasie rzeczywistym.

Błędy „Brak pola”

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ą na zapytanie a żądaniem stanu raportu 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 SYNCHRONIZACJI, 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ą stanu raportu.

Rozwiązanie: upewnij się, że funkcja Report State jest wywoływana za każdym razem, gdy zmienia się stan urządzenia, oraz że funkcje Report State 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: 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 o stanie tego urządzenia (stan jest pusty, a zgłoszony znacznik czasu jest ustawiony na epokę), mimo że wyniki ZAPYTANIA zawierają bieżący stan. Oznacza to, że aktualizacje stanu nie są wywoływane, nie docierają do HomeGraph lub urządzenie nie zgłasza prawidłowo zmian w stanie połączenia lub działania.

Rozwiązanie: upewnij się, że funkcja Report State jest wywoływana i wysyłana 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 działały prawidłowo.