Stan raportu

Report State to ważna funkcja, która umożliwia akcji Google Home proaktywne zgłaszanie najnowszego stanu urządzenia użytkownika do Google Home Graph, zamiast czekać na intencję QUERY.

Report State zgłasza do Google stany urządzeń użytkowników z określonym agentUserId powiązanym z tymi urządzeniami (przesyłanym w pierwotnym SYNC żądaniu). Gdy Google Assistant chce wykonać działanie które wymaga zrozumienia bieżącego stanu urządzenia, może po prostu sprawdzić informacje o stanie w Home Graph zamiast wysyłać intencję QUERY do różnych chmur innych firm przed wysłaniem EXECUTE intencji.

Bez funkcji Report State w przypadku świateł od różnych dostawców w salonie polecenie Ok Google, rozjaśnij salon wymaga rozwiązania wielu intencji QUERY wysyłanych do wielu chmur, a nie tylko sprawdzenia bieżących wartości jasności na podstawie tego, co zostało wcześniej zgłoszone. Aby zapewnić jak najlepsze wrażenia użytkownikom, Assistant musi znać bieżący stan urządzenia, bez konieczności wysyłania żądania do urządzenia i otrzymywania odpowiedzi.

Po początkowym żądaniu SYNC dotyczącym urządzenia platforma wysyła intencję QUERY która zbiera stan urządzenia w celu wypełnienia Home Graph. Od tego momentu Home Graph przechowuje tylko stan, który jest wysyłany za pomocą Report State.

Podczas wywoływania funkcji Report State pamiętaj, aby podać pełne dane stanu dla danej cechy. Home Graph aktualizuje stany na podstawie poszczególnych cech i zastępuje wszystkie dane dotyczące tej cechy, gdy zostanie wykonane wywołanie funkcji Report State. Jeśli na przykład zgłaszasz stan cechy StartStop, ładunek musi zawierać wartości zarówno dla isRunning jak i isPaused.

Rozpocznij

Aby zaimplementować funkcję Report State, wykonaj te czynności:

• Włącz interfejs Google HomeGraph API.
• Utwórz klucz konta usługi.
• Wywołaj interfejs API.

Włącz interfejs Google HomeGraph API

1. W Google Cloud Console otwórz stronę HomeGraph API.

   Otwórz stronę HomeGraph API
2. Wybierz projekt, który odpowiada identyfikatorowi projektu smart home.
3. Kliknij WŁĄCZ.

Utwórz klucz konta usługi

Aby wygenerować klucz konta usługi z Google Cloud Console, wykonaj te instrukcje:

1. W Google Cloud Console otwórz stronę Konta usługi.

   Otwórz stronę Konta usługi.

   Zanim przejdziesz na stronę Konta usługi, może być konieczne wybranie projektu.

2. Kliknij addUtwórz konto usługi.

3. W polu Nazwa konta usługi wpisz nazwę.

4. W polu Identyfikator konta usługi wpisz identyfikator.

5. W polu Opis konta usługi wpisz opis.

6. Kliknij Utwórz i kontynuuj.

7. W menu Rola wybierz Konta usługi > Twórca tokenów tożsamości OpenID Connect konta usługi.

8. Kliknij Dalej.

9. Kliknij Gotowe.

10. Na liście kont usługi wybierz utworzone konto usługi i wybierz Zarządzaj kluczami z menu more_vert Działania.

11. Kliknij Dodaj klucz > Utwórz nowy klucz.

12. W polu Typ klucza wybierz opcję JSON.

13. Kliknij Utwórz. Na komputer zostanie pobrany plik JSON zawierający klucz.

Wywołaj interfejs API

Wybierz opcję z kart poniżej:

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

  // Get Application Default credentials.
  GoogleCredentials credentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

  // Create Home Graph service client.
  HomeGraphService homegraphService =
      new HomeGraphService.Builder(
              GoogleNetHttpTransport.newTrustedTransport(),
              GsonFactory.getDefaultInstance(),
              new HttpCredentialsAdapter(credentials))
          .setApplicationName("HomeGraphExample/1.0")
          .build();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request).execute();
}
    

Testowanie funkcji Report State

Aby przygotować integrację typu Cloud-to-cloud do certyfikacji, musisz przetestować funkcję Report State.

W tym celu zalecamy użycie narzędzia Home Graph Viewer, które jest samodzielną aplikacją internetową i nie wymaga pobierania ani wdrażania.

Panel Report State jest nadal dostępny, ale został wycofany i nie jest już obsługiwany.

Panel Report State

Wymagania wstępne

Aby móc przetestować integrację Cloud-to-cloud, musisz mieć klucz konta usługi i agentUserId. Jeśli masz już klucz konta usługi i agentUserId przeczytaj artykuł Wdrażanie panelu Report State Dashboard.

Wdrażanie panelu Report State

Gdy masz już klucz konta usługi i identyfikator agentUserId dla swojego projektu, pobierz i wdróż najnowszą wersję z Report State panelu. Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami zawartymi w pliku README.MD.

Po wdrożeniu panelu Report State otwórz go pod tym adresem URL (zastąp your_project_id identyfikatorem projektu):

http://<your-project-id>.appspot.com

W panelu wykonaj te czynności:

• Wybierz plik klucza konta.
• Dodaj identyfikator agentUserId.

Następnie kliknij Lista.

Wyświetli się lista wszystkich Twoich urządzeń. Gdy lista zostanie wypełniona, możesz użyć przycisku Odśwież , aby zaktualizować stany urządzeń. Jeśli stan urządzenia się zmieni, wiersz zostanie podświetlony na zielono.

Rozbieżności w funkcji Report State

Dokładność stanu raportu opartego na zapytaniach określa, jak dobrze najnowszy stan raportu dotyczący urządzenia odpowiada jego stanowi, gdy użytkownik o niego zapyta. Ta wartość powinna wynosić 99,5%. Więcej informacji o bieżącym stanie dokładności funkcji Report State w Twoim projekcie znajdziesz w artykule Stan urządzenia – dokładność stanu. Szczegóły dziennika rozbieżności funkcji Report State możesz też sprawdzić w Eksploratorze logów.

Oto przykład dziennika rozbieżności funkcji Report State:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Definicje pól dziennika rozbieżności funkcji Report State

Zwrócone kody błędów

Podczas wywoływania funkcji Report State możesz otrzymać jedną z tych odpowiedzi o błędzie. Te odpowiedzi mają postać kodów stanu HTTP.

400 Nieprawidłowe żądanie

Serwer nie mógł przetworzyć żądania wysłanego przez klienta 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.

404 Nie znaleziono

Nie udało się znaleźć żądanego zasobu, ale może on być dostępny w przyszłości. Zwykle oznacza to, że nie możemy znaleźć żądanego urządzenia. Może to też oznaczać, że konto użytkownika nie jest połączone z Google lub że otrzymaliśmy nieprawidłowy identyfikator agentUserId. Upewnij się, że identyfikator agentUserId jest zgodny z wartością podaną w odpowiedzi SYNC i że prawidłowo obsługujesz intencje DISCONNECT.

Jeśli wywołanie funkcji ReportState nie powiedzie się z powodu błędu 404 NOT_FOUND, oznacza to, że występuje niezgodność synchronizacji między Twoją chmurą a Home Graph. Może się tak zdarzyć, jeśli urządzenie zostanie usunięte z Home Graph lub jeśli użytkownik odłączy swoje konto.

Aby obsługiwać błędy 404 z funkcji Report State, wykonaj te czynności:

1. Sprawdź stan konta użytkownika: wywołaj devices.sync dla identyfikatora agentUserId, który zwrócił błąd 404. Pomoże to ustalić, czy błąd dotyczy całego konta użytkownika, czy konkretnego urządzenia.
   • Jeśli SYNC zwraca błąd 404, konto użytkownika nie jest już połączone z Google. Przestań wysyłać funkcję Report State i żądaj synchronizacji urządzeń tego użytkownika.
   • Jeśli SYNC zwraca 200 OK, konto użytkownika jest nadal połączone, co oznacza, że błąd 404 dotyczy konkretnego urządzenia.
2. Uzgadnianie listy urządzeń: jeśli SYNC zwraca 200 OK, musisz określić, które urządzenia nie są już znane Google. Zalecamy porównanie listy urządzeń, które Google ma dla użytkownika, z bazą danych urządzeń i zidentyfikowanie urządzeń w Twoim systemie, których nie ma na liście Google. Jeśli urządzenie powinno być zsynchronizowane z Google, ale nie jest jeszcze udostępnione Google, użyj SYNC, aby upewnić się, że urządzenie jest zsynchronizowane z Google. Jeśli urządzenie powinno zostać odłączone od Google, przestań zgłaszać stan tego urządzenia i kontynuuj zgłaszanie stanu innych prawidłowych urządzeń w ramach tego identyfikatora agentUserId.

Raportowanie stanu online i offline

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }