Stan raportu

Report State to ważna funkcja, która pozwala akcji Google Home proaktywnie zgłaszać najnowszy stan 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 powiązanym z nimi określonym agentUserId (wysłanym w pierwotnym żądaniu SYNC). Gdy Google Assistant chce wykonać działanie, które wymaga znajomości 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 intencji EXECUTE.

Bez Report State, gdy w salonie są światła od wielu dostawców, polecenie OK Google, rozjaśnij salon wymaga rozpoznania wielu intencji QUERY wysyłanych do wielu chmur, a nie po prostu sprawdzenia bieżących wartości jasności na podstawie tego, co zostało wcześniej zgłoszone. Aby zapewnić użytkownikom jak najlepsze wrażenia, Assistant musi mieć aktualny stan urządzenia bez konieczności komunikacji z nim.

Po początkowym SYNC urządzenia platforma wysyła intencję QUERY, która zbiera stan urządzenia, aby wypełnić Home Graph. Po tym czasie Home Graph przechowuje tylko stan wysłany z Report State.

Podczas wywoływania Report State podaj pełne dane stanu dla danej cechy. Home Graph aktualizuje stany na podstawie cech i zastępuje wszystkie dane dotyczące danej cechy, gdy wywoływana jest funkcja Report State. Jeśli na przykład raportujesz stan cechy StartStop, ładunek musi zawierać wartości zarówno dla isRunning, jak i isPaused.

Rozpocznij

Aby wdrożyć Report State, wykonaj te czynności:

• Włączanie interfejsu Google HomeGraph API
• Tworzenie klucza konta usługi
• Wywoływanie interfejsu API

Włączanie interfejsu 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.

Tworzenie klucza 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. Wybierz utworzone konto usługi z listy kont 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. Plik JSON zawierający klucz zostanie pobrany na komputer.

Wywoływanie interfejsu API

Wybierz opcję na kartach 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();
}
    

Stan raportu z testu

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

Zalecamy użycie w tym celu 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 stanu raportu

Wymagania wstępne

Zanim przetestujesz integrację z Cloud-to-cloud, musisz mieć klucz konta usługi i agentUserId. Jeśli masz już klucz konta usługi i agentUserId, zapoznaj się z artykułem Wdrażanie panelu Report State.

Wdrażanie panelu stanu raportu

Gdy będziesz mieć klucz konta usługi i identyfikator użytkownika agenta dla swojego projektu, pobierz i wdróż najnowszą wersję z panelu Report State. Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami zawartymi w dołączonym pliku README.MD.

Po wdrożeniu panelu Report State uzyskaj do niego dostęp, korzystając z tego adresu 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 agentUserId

Następnie kliknij Lista.

Wyświetlane są wszystkie Twoje urządzenia. Gdy lista zostanie wypełniona, możesz użyć przycisku Odśwież, aby zaktualizować stany urządzeń. Jeśli stan urządzenia ulegnie zmianie, wiersz zostanie podświetlony na zielono.

Zgłaszanie rozbieżności stanów

Dokładność stanu raportu na podstawie zapytania określa, jak dobrze najnowszy stan raportu urządzenia odpowiada stanowi urządzenia, gdy użytkownik wysyła zapytanie. Ta wartość powinna wynosić 99,5%. Więcej informacji o bieżącym stanie dokładności raportowania stanu w projekcie znajdziesz w artykule Stan urządzenia – dokładność stanu. Szczegóły dziennika rozbieżności stanu raportu możesz też wyświetlić w Eksploratorze logów.

Oto przykład dziennika rozbieżności w raportowaniu stanu:

{
  "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 stanu raportu

Odpowiedzi na błędy

Podczas wywoływania Report State możesz otrzymać jedną z tych odpowiedzi o błędzie. Odpowiedzi te 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. Częste przyczyny to nieprawidłowo sformatowany kod JSON lub użycie null zamiast „” w przypadku wartości ciągu znaków.

Błąd 404 (nie znaleziono)

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

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

Aby obsłużyć błędy 404 ze stanu raportu, wykonaj te czynności:

1. Sprawdź stan konta użytkownika: wywołaj metodę devices.sync dla zasobu 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 zwróci błąd 404, konto użytkownika nie jest już połączone z Google. Przestań wysyłać raporty o stanie i żądania synchronizacji dla urządzeń tego użytkownika.
   • Jeśli SYNC zwróci kod 200 OK, konto użytkownika jest nadal połączone, co oznacza, że błąd 404 jest związany z urządzeniem.
2. Uzgodnij listę urządzeń: jeśli SYNC zwraca kod 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 systemie, których nie ma na liście Google. Jeśli urządzenie powinno być zsynchronizowane z Google, ale nie zostało 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ń raportować stan tego konkretnego urządzenia i kontynuuj raportowanie w przypadku innych prawidłowych urządzeń w ramach tego 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": {},
        }
      }
    }