Stan raportu

Report State to ważna funkcja, która umożliwia działaniu 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żytkownika z określonym agentUserId powiązanym z tymi urządzeniami (przesł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 intencji EXECUTE.

Bez funkcji Report State w przypadku świateł od różnych dostawców w salonie polecenie OK Google, rozjaśnij mój salon wymaga rozwiązania wielu intencji QUERY wysł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ątkowej synchronizacji SYNC 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 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 zobacz Wdrażanie panelu Report State.

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 dla 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 sekcji 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

Odpowiedzi na błędy

Podczas wywoływania funkcji Report State możesz otrzymać jedną z tych odpowiedzi na błędy. Odpowiedzi te mają postać kodów stanu HTTP.

• 400 Bad Request – 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 Not Found – nie znaleziono żą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. Sprawdź czy agentUserId odpowiada wartości podanej w odpowiedzi SYNC i czy prawidłowo obsługujesz intencje DISCONNECT.

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": {},
        }
      }
    }