Stan raportu

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

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

Bez Report State, jeśli w salonie są światła od różnych dostawców, polecenie OK Google, rozjaśnij światło w salonie wymaga rozwiązania wielu QUERY intencji wysłanych do wielu chmur, zamiast po prostu sprawdzenia bieżących wartości jasności na podstawie wcześniejszych danych. Aby zapewnić użytkownikom jak najlepsze wrażenia, Assistant musi mieć bieżący stan urządzenia bez konieczności wielokrotnego uruchamiania urządzenia.

Po początkowej wartości SYNC dotyczącej urządzenia platforma wysyła intencję QUERY, która zbiera stan urządzenia i wypełnia je Home Graph. Po tym czasie Home Graph przechowuje tylko stan wysłany z Report State.

Przy wywołaniu funkcji Report State podaj pełne dane o stanie dla danej cechy. Home Graph aktualizuje stany na podstawie atrybutu i zapisuje wszystkie dane dotyczące tego atrybutu, gdy zostanie wywołane Report State. Jeśli na przykład przekazujesz stan 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 sekcji Google Cloud Console otwórz stronę HomeGraph API.

    Otwórz stronę interfejsu HomeGraph API
  2. Wybierz projekt, który pasuje do identyfikatora 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:

Uwaga: podczas wykonywania tych czynności upewnij się, że używasz prawidłowego projektu Google Cloud Platform. Jest to projekt, który pasuje do identyfikatora projektu smart home.
  1. W panelu 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. Na liście Rola wybierz Konta usługi > Twórca tokena konta usługi.

  6. W polu Typ klucza wybierz opcję JSON.

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

Wywoływanie interfejsu API

Wybierz opcję na 1 z tych kart:

HTTP

Usługa Home Graph udostępnia punkt końcowy HTTP.

  1. Użyj pobranego pliku JSON konta usługi, aby utworzyć token internetowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie za pomocą konta usługi.
  2. Aby uzyskać token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph, użyj polecenia 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ładowa prośba JSON dotycząca stanu raportu i powiadomienia:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
  6. Połącz stan raportu i dane JSON powiadomienia z tokenem w żądaniu HTTP POST do punktu końcowego Google Home Graph. Oto przykład żądania wysyłanego w wierszu poleceń za pomocą 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

Usługa Home Graph udostępnia punkt końcowy gRPC.

  1. Pobierz definicję usługi protocol buffers dla interfejsu Home Graph API.
  2. Aby wygenerować atrapy klienta w jednym z obsługiwanych języków, postępuj zgodnie z instrukcjami podanymi w dokumentacji dla deweloperów gRPC.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Interfejs Node.js Client API od Google udostępnia powiązania dla interfejsu API Home Graph.

  1. Inicjuje usługę google.homegraph przy użyciu domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca Promise z funkcją 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 HomeGraph API for Java zawiera powiązania dla interfejsu Home Graph API.

  1. Inicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca ona 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 z testu

Zalecane narzędzia do wykonania tego zadania

Aby przygotować działanie do certyfikacji, musisz je przetestować.Report State

W tym celu zalecamy użycie narzędzia Home Graph Viewer, 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 raportu

Wymagania wstępne

Aby przetestować działanie akcji, 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 Stan raportu

Gdy masz klucz konta usługi i identyfikator użytkownika agenta dla projektu, pobierz najnowszą wersję z Report StatePulpit. Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami podanymi w dołączonym pliku README.MD.

Po wdrożeniu panelu Report State możesz uzyskać 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.

Wszystkie Twoje urządzenia są widoczne na liście. Po wypełnieniu listy możesz użyć przycisku Odśwież, aby zaktualizować stany urządzeń. Jeśli nastąpiła zmiana stanu urządzenia, wiersz zostanie wyróżniony na zielono.

Odpowiedzi na błędy

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 Bad Request – serwer nie może przetworzyć żądania wysłanego przez klienta z powodu błędnej składni. Typowe przyczyny to źle sformatowany plik JSON lub użycie znaku null zamiast znaku „” w przypadku wartości ciągu znaków.
  • 404 Not Found – nie znaleziono żądanego zasobu, ale może być on 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łowy agentUserId. Upewnij się, że agentUserId jest zgodny z wartością w odpowiedzi SYNC i że poprawnie obsługujesz intencje DISCONNECT.