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 wysokiej jakości ekosystemu 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 dla 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, co wskazuje na problem, który może wpływać 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 poniższy przycisk nie przekieruje Cię bezpośrednio do panelu, możesz go otworzyć, wybierając kolejno strony Przegląd i Panele, a następnie na liście Moje panele wybierając panel Google Home Vitals (Cloud).

Otwórz Panel

Dane od Google do partnera

Dane Query/Execute Success Rate >= 99.5% mierzą, jak często polecenia użytkowników są wykonywane prawidłowo, 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 jeszcze 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 zostało wykonane pomimo ostrzeżenia.

Co oznacza „niepowodzenie”?

Błędy znalezione w sekcji Typowe kody błędów platformy, które są oznaczone jako Wymagające działania ze strony partnera, są uznawane za „Niepowodzenia” podczas obliczania odsetka udanych zapytań i wykonań. 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 wykonanie żądanego działania i pomaga zapewnić, że użytkownicy nie będą musieli zbyt długo czekać, np. kilka sekund na wyłączenie światła.

Dane o opóźnieniach

Opóźnienie to kluczowy wskaźnik szybkości reakcji integracji z punktu widzenia użytkownika. Na panelu śledzone jest opóźnienie 90 centyla (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 urządzenia (np. żarówki), ponieważ często wiąże się to z opóźnieniami w lokalnej sieci typu mesh, które nie są związane ze ścieżką chmura-chmura.

Opcje skracania czasu oczekiwania

Zalecenia dotyczące architektury w przypadku kierowania 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ż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.

   • Zaleta: 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.

   • Wdrożenie: upewnij się, że Twój dostawca DNS jest zoptymalizowany pod kątem punktów wyjścia Google. Gdy regionalne usługi realizacji zamówień Google (np. w Stanach Zjednoczonych, UE lub Azji) rozwiążą 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 ma największy wpływ 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.

   Wdrożenie: 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ń są prawidłowe w Google Home, urządzenia są dodawane i usuwane, automatyzacje są wyzwalane, a zdarzenia historyczne pojawiają się na karcie Aktywność w Google Home app (GHA).

Współczynnik powodzeń jest obliczany na podstawie kodów odpowiedzi HTTP zwracanych przez Google, gdy Twoja chmura przesyła aktualizacje stanu. Aby uniknąć karania partnerów za problemy z infrastrukturą po stronie Google, w obliczeniach pomijane są wewnętrzne błędy Google. Wywołania interfejsu API uwzględniane w obliczeniach znajdziesz w dokumentacji interfejsu 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 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: zapoznaj się 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 i ograniczenia 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 AI, takich jak Zapytaj Home. Jeśli dokładność stanu jest niska, automatyzacje mogą się nie uruchamiać, a wpisy historii mogą się nie pojawiać we właściwym czasie na karcie Aktywność urządzenia GHA. Więcej informacji znajdziesz w artykule Stan raportu. Uwaga: docelowa dokładność stanu musi być osiągnięta w przypadku WSZYSTKICH obsługiwanych cech.

1. Komponenty dokładności

Dane są wyliczane na podstawie „próbek”, w przypadku których Google może zweryfikować zgłoszony stan na podstawie znanego wyniku intencji. Dokładność techniczną ocenia się w 2 różnych obszarach:

• Dokładność oparta na zapytaniu: weryfikowana, gdy użytkownik lub system aktywnie sprawdza bieżący stan urządzenia.
• DOKŁADNOŚĆ WYKONANIA: weryfikowana przez ocenę stanu urządzenia po wykonaniu polecenia, który jest zgłaszany po żądaniu sterowania.

2. Dane w panelu (obliczane co godzinę)

Panel oblicza dokładność na podstawie godzinnego przedziału. Aby zapewnić wiarygodność statystyczną i uniknąć karania integracji z niskim poziomem szumu sygnału, Google stosuje minimalny próg natężenia ruchu. Jeśli w przypadku określonej kombinacji cechy i urządzenia w 5-dniowym przedziale ruchomym zgromadzono mniej niż 100 próbek, dokładność jest uznawana za statystycznie nieistotną i ustawiana na N/A.

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

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

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

• Dokładność zapytań (%) = (Próbki dokładnych zapytań w ciągu godziny) / (Łączna liczba próbek zapytań w ciągu godziny)
• %dokładności wykonania = (próbki dokładnego wykonania w ciągu godziny) / (wszystkie próbki wykonania w ciągu godziny)

Wynik dokładności cechy (obliczany dla każdej cechy) = SUMA(Przykłady dokładnych zapytań + Przykłady dokładnych wykonań) / SUMA(Przykłady wszystkich zapytań + Przykłady wszystkich wykonań)

Ocena jakości uwzględnia bezwzględne minimum skuteczności w Twoim ekosystemie, dlatego każda obsługiwana i kwalifikująca się cecha musi indywidualnie spełniać docelową dokładność stanu na poziomie ≥ 99,5% (nie jest to średnia z różnych cech).

Ten widok zapobiega maskowaniu problemów z dokładnością na urządzeniach o mniejszej liczbie pomiarów przez urządzenia o dużej liczbie pomiarów i doskonałej dokładności. Partnerzy, którzy obawiają się, że niedostatecznie wykorzystywane cechy obniżą ich wynik, mogą mieć pewność, że rzadko używana cecha jest automatycznie chroniona przez sprawdzanie minimalnej wielkości ruchu i nie będzie uwzględniana w wyniku Najniższy typ i cecha, chyba że osiągnie wymagany próg próbki.

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 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 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 ReportState 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ą 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 stan raportu jest wywoływany i wysyłany 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.