Stan raportu

Ważna informacja: aby przesłać integrację Cloud-to-cloud, musisz wdrożyć Report State.

Report State to ważna funkcja, która umożliwia akcji Google 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 podjąć działanie, które wymaga poznania 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, 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ą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.

Uwaga: informacje o kolejnych stanach zwracane za pomocą intencji EXECUTE i QUERY nie będą przechowywane w Home Graph. Twoim obowiązkiem jest zadzwonienie do Report State, aby zaktualizować Home Graph o najnowsze informacje o stanie.

Podczas wywoływania funkcji Report State pamiętaj, aby podać pełne dane stanu 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
• Tworzenie klucza konta usługi
• Wywoływanie interfejsu API

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 odpowiada Twojemu identyfikatorowi projektu smart home.
3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

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

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. Na liście 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. Plik JSON z kluczem zostanie pobrany na komputer.

Wywoływanie interfejsu API

Wybierz opcję na 1 z tych kart:

HTTPgRPCNode.jsJava

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:

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

3. Utwórz żądanie JSON za pomocą interfejsu API agentUserId. Oto przykładowa prośba w formacie JSON dotycząca stanu raportu i powiadomienia:

{
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}

4. Połącz stan zgłoszenia i token w pliku JSON powiadomienia z żądaniem HTTP POST do punktu końcowego Google Home Graph. Oto przykład żądania wysyłanego w wierszu poleceń za pomocą polecenia curl, które możesz wykorzystać do przeprowadzenia testu:

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

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.

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

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

Biblioteka klienta HomeGraph API dla języka Java udostępnia elementy wiążące dla interfejsu Home Graph API.

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

Uwaga: po otrzymaniu intencji DISCONNECT należy przerwać wywoływanie funkcji Report State, co oznacza, że użytkownik odłączył swoje konto.

Stan raportu z testu

• Wyświetlający Home Graph

Zalecane narzędzia do wykonania tego zadania

Aby przygotować integrację Cloud-to-cloud do certyfikacji, ważne jest przetestowanie 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

Wycofany: panel Report State został wycofany.

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 paneluReport State.

Uwaga: klucz JSON służący do certyfikacji różni się od klucza JSON do użytku produkcyjnego. Utwórz nowy tymczasowy klucz konta usługi na potrzeby testowania, który możesz usunąć po zakończeniu certyfikacji.

Jak utworzyć klucz konta usługi

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

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. Na liście 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. Plik JSON z kluczem zostanie pobrany na komputer.

Jak pobrać agentUserId

Aby odzyskać agentUserId:

1. Otwórz narzędzia OAuth Playground.
2. Kliknij ikonę koła zębatego w prawym górnym rogu, aby otworzyć okno Konfiguracja OAuth 2.0.
3. W polu Punkty końcowe OAuth wybierz Niestandardowe.
4. Podaj te parametry łączenia kont, używając wartości ustawionych w konsoli Actions podczas tworzenia projektu inteligentnego domu. Kliknij Zamknij, aby zapisać zmiany.
   • Punkt końcowy autoryzacji: w konsoli ustaw ten parametr na URL autoryzacji.
   • Punkt końcowy tokena: ustaw ten parametr na URL tokena w konsoli.
   • Identyfikator klienta OAuth: ustaw tę wartość taką samą jak w konsoli.
   • Tajne hasło klienta OAuth: ustaw tę wartość taką samą jak w konsoli.

   

   Rysunek 1.Konfiguracja OAuth 2.0

5. Rozwiń Krok 1. Wybierz i autoryzuj interfejsy API. W polu tekstowym z treścią „Wpisz własne zakresy” wpisz „urządzenia” i kliknij Autoryzuj interfejsy API.
   Uwaga: jeśli w konsoli zostały określone dodatkowe zakresy, musisz je też określić w kroku 1.
6. Jeśli poprzedni krok zakończył się powodzeniem, zostaniesz przekierowany do punktu końcowego OAuth. Zaloguj się na konto użytkownika, które chcesz przetestować. Po zalogowaniu się zostaniesz przekierowany z powrotem do narzędzia OAuth Playground, gdzie krok 2 będzie rozwinięty i zawierać będzie wygenerowany dla Ciebie kod autoryzacji.
7. Aby uzyskać token odświeżania i token dostępu, kliknij Wymień autoryzowany kod na tokeny.
8. W sekcji Krok 3. Skonfiguruj żądanie do interfejsu API wykonaj te czynności:
   1. Ustaw Metoda HTTP na POST.
   2. Ustaw parametr Request URI na adres URL realizacji.

   3. Kliknij Wpisz treść żądania i dodaj ten przykładowy tekst:

      {
        "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
        "inputs": [{
          "intent": "action.devices.SYNC"
        }]
      }
              

   4. Kliknij Wyślij prośbę.
9. W odpowiedzi znajdź wartość pola „agentUserId”.

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 – żądanego zasobu nie można było znaleźć, 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 adres agentUserId. Upewnij się, że agentUserId jest zgodny z wartością w odpowiedzi na żądanie SYNC i że prawidłowo obsługujesz intencje DISCONNECT.

Uwaga: gdy urządzenie jest offline, w ciągu 5 minut od momentu, gdy urządzenie przestało działać, należy zgłosić to w sekcji {"online": false}Zgłoś stan. Więcej informacji znajdziesz w sekcji Błędy i wyjątki.