Stan raportu

Report State to ważna funkcja, dzięki której działanie Home może aktywnie raportować najnowszy stan urządzenia użytkownika z powrotem na Google Home Graph, zamiast czekać na działanie QUERY.

Report State zgłasza do Google stany urządzeń użytkowników, które są z nimi powiązane (agentUserId, wysłane w pierwotnym żądaniu SYNC). Gdy Google Assistant chce wykonać działanie, które wymaga zrozumienia bieżącego stanu urządzenia, może przed wysłaniem intencji EXECUTE uzyskać informacje o stanie w Home Graph, zamiast wysyłać intencję QUERY do różnych chmur zewnętrznych.

Jeśli nie masz Report State w salonie, polecenie OK Google, rozjaśnij salon wymaga rozwiązania kilku intencji QUERY wysłanych do wielu chmur, w przeciwieństwie do sprawdzania bieżących wartości jasności na podstawie wcześniej zgłoszonych informacji. Aby zapewnić użytkownikom jak najlepsze wrażenia, Assistant musi mieć bieżący stan urządzenia bez konieczności przesyłania go w obie strony.

Po pierwotnym SYNC na potrzeby platformy platforma wysyła intencję QUERY, która zbiera stan urządzenia, aby zapełnić Home Graph. Następnie Home Graph zapisuje tylko stan, który został wysłany z użyciem Report State.

Gdy wywołujesz funkcję Report State, podaj pełne dane stanu dla danej cechy. Home Graph aktualizuje stany poszczególnych cech i zastępuje wszystkie dane dotyczące tej cechy w wywołaniu funkcji Report State. Jeśli na przykład raportujesz stan dla atrybutu StartStop, ładunek musi zawierać wartości zarówno dla isRunning, jak i isPaused.

Rozpocznij

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

Włącz interfejs Google HomeGraph API

  1. W Google Cloud Console przejdź do strony HomeGraph API.

    Otwórz stronę interfejsu HomeGraph API
  2. Wybierz projekt zgodny z identyfikatorem projektu smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z Google Cloud Console:

Uwaga: podczas wykonywania tych czynności sprawdź, czy używasz odpowiedniego projektu GCP. Ten projekt pasuje do identyfikatora projektu smart home.
  1. W sekcji Google Cloud Console otwórz stronę Utwórz klucz konta usługi.

    Otwórz stronę tworzenia klucza konta usługi
  2. Z listy Konto usługi wybierz Nowe konto usługi.
  3. W polu Nazwa konta usługi wpisz nazwę.
  4. W polu Identyfikator konta usługi wpisz identyfikator.
  5. Z listy Rola wybierz Konta usługi > Twórca tokenów konta usługi.

  6. W polu Typ klucza wybierz opcję JSON.

  7. Kliknij Utwórz. Plik JSON zawierający klucz zostanie pobrany na komputer.

Wywoływanie interfejsu API

Wybierz opcję na poniższych kartach:

HTTP

Home Graph udostępnia punkt końcowy HTTP.

  1. Użyj pobranego pliku JSON konta usługi, aby utworzyć token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie przy użyciu konta usługi.
  2. Uzyskaj token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph za pomocą oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Utwórz żądanie JSON za pomocą agentUserId. Oto przykładowe żądanie JSON dotyczące stanu raportu i powiadomienia:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Połącz stan raportu i kod JSON powiadomienia oraz token w żądaniu HTTP POST z punktem końcowym Google Home Graph. Oto przykład, jak utworzyć żądanie w wierszu poleceń przy użyciu polecenia curl:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

Home Graph udostępnia punkt końcowy gRPC.

  1. Pobierz definicję usługi buforów protokołów dla interfejsu Home Graph API.
  2. Wykonaj instrukcje podane w dokumentacji dla programistów gRPC, aby wygenerować wycinki dla jednego z obsługiwanych języków.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsu API Google udostępnia powiązania interfejsu Home Graph API.

  1. Zainicjuj usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification za pomocą polecenia ReportStateAndNotificationRequest. Zwraca wartość Promise za pomocą parametru ReportStateAndNotificationResponse.
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
          }
        }
      }
    }
  }
});
    

Java

Biblioteka klienta interfejsu API GraGraph dla języka Java zapewnia powiązania z interfejsem Home Graph API.

  1. Zainicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification metodą ReportStateAndNotificationRequest. Zwraca wartość ReportStateAndNotificationResponse.
  // 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);
}
    

Stan raportu testowego

Zalecane narzędzia

Aby przygotować swoje działanie do uzyskania certyfikatu, ważne jest przetestowanie Report State.

Aby to zrobić, zalecamy korzystanie z narzędzia Home Graph Przeglądarka, które jest samodzielną aplikacją internetową, która nie wymaga pobierania ani wdrażania.

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

Panel stanu raportów

Wymagania wstępne

Aby przetestować działanie, musisz mieć klucz konta usługi i agentUserId. Jeśli masz już klucz konta usługi, a agentUserId zapoznaj się z artykułem Wdrażanie panelu Report State,

Wdrażanie panelu stanu raportu

Gdy uzyskasz klucz konta usługi i identyfikator użytkownika agenta, pobierz i wdróż najnowszą wersję z paneluReport State. Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami z dołączonego pliku README.MD.

Po wdrożeniu panelu Report State uzyskasz dostęp do panelu z tego adresu URL (zastąp identyfikator_projektu swoim identyfikatorem projektu):

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

W panelu wykonaj te czynności:

  • Wybierz plik z kluczem konta
  • Dodaj identyfikator UserAgent

Następnie kliknij Lista.

Zobaczysz wszystkie swoje urządzenia. Gdy lista będzie gotowa, możesz zaktualizować ją, klikając przycisk Odśwież. Jeśli zmieni się stan urządzenia, wiersz zostanie wyróżniony na zielono.

Reakcje na błędy

Podczas wywoływania funkcji Report State możesz zobaczyć jedną z tych odpowiedzi dotyczących błędów. Te odpowiedzi mają postać kodów stanu HTTP.

  • 400 Bad Request – serwer nie może przetworzyć żądania wysłanego przez klienta ze względu na nieprawidłową składnię. Typowe przyczyny to zniekształcony kod JSON lub użycie wartości „null” zamiast „" jako wartości ciągu.
  • 404 Not Found – żądanego zasobu nie udało się znaleźć, 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 otrzymaliśmy nieprawidłowe żądanie agentUserId. Upewnij się, że agentUserId odpowiada wartości podanej w odpowiedzi SYNC i że obsługujesz intencje DISCONNECT.