Stan raportu

Report State to ważna funkcja, dzięki której akcja Home aktywnie zgłasza najnowszy stan urządzenia użytkownika do Google Home Graph, zamiast czekać na intencję QUERY.

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

Jeśli Report State w salonie nie ma źródeł światła, polecenie OK Google, rozjaśnij mój salon wymaga rozwiązania wielu QUERY intencji wysłanych do wielu chmur, a nie po prostu sprawdzania bieżących wartości jasności na podstawie dotychczasowych informacji. Ze względu na wygodę użytkowników Assistant musi mieć aktualny stan urządzenia, bez konieczności przesyłania danych w obie strony do urządzenia.

Po początkowym wywołaniu SYNC dla urządzenia platforma wysyła intencję QUERY, która zbiera informacje o stanie urządzenia w celu wypełnienia żądania Home Graph. Od tego momentu Home Graph przechowuje tylko stan, który jest wysyłany za pomocą metody Report State.

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

Rozpocznij

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

Włącz interfejs Google HomeGraph API

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

    Otwórz stronę interfejsu HomeGraph API
  2. Wybierz projekt pasujący do identyfikatora projektu w smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

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

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

    Otwórz stronę Tworzenie 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 Twój komputer.

Wywoływanie interfejsu API

Wybierz opcję na jednej z tych kart:

HTTP

Home Graph określa punkt końcowy HTTP.

  1. Użyj pobranego pliku JSON konta usługi, aby utworzyć token sieciowy JSON (JWT). Więcej informacji znajdziesz w sekcji Uwierzytelnianie za pomocą 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 z atrybutem agentUserId. Oto przykładowe żądanie JSON dla stanu raportu i powiadomienia:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Połącz kod JSON Stan raportu i powiadomienie oraz token w żądaniu HTTP POST z punktem końcowym Google Home Graph. Oto przykład, jak w ramach testu wysłać żądanie 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

Home Graph udostępnia punkt końcowy gRPC

  1. Pobierz definicję usługi buforów protokołów dla interfejsu Home Graph API.
  2. Postępuj zgodnie z dokumentacją dla programistów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsów API Google dostarcza powiązania dla interfejsu API Home Graph.

  1. Zainicjuj usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z metodą ReportStateAndNotificationRequest. Zwraca wartość Promise z parametrem 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 dla języka Java zawiera powiązania dla interfejsu Home Graph API.

  1. Zainicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification za pomocą metody 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

Narzędzia zalecane do wykonania tego zadania

Aby przygotować działanie do uzyskania certyfikatu, trzeba przetestować Report State.

W tym celu zalecamy użycie narzędzia Home Graph Wyświetlający – jest to samodzielna aplikacja internetowa, 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 móc przetestować działanie, 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.

Wdrażanie panelu stanu raportu

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

Po wdrożeniu panelu Report State możesz uzyskać do niego dostęp 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 agenta_agenta

Następnie kliknij Lista.

Zobaczysz listę wszystkich urządzeń. Gdy lista będzie gotowa, możesz zaktualizować stany urządzeń, klikając przycisk Odśwież. Jeśli nastąpi zmiana stanu urządzenia, wiersz zostanie podświetlony na zielono.

Odpowiedzi na błędy

Podczas wywoływania funkcji Report State możesz otrzymać jedną z tych odpowiedzi o błędzie. 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 null zamiast „” dla wartości ciągu.
  • 404 Not Found – 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 otrzymaliśmy nieprawidłowy atrybut agentUserId. Sprawdź, czy agentUserId jest zgodna z wartością podaną w odpowiedzi SYNC i poprawnie obsługujesz intencje DISCONNECT.