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
-
W Google Cloud Console otwórz stronę HomeGraph API.
Otwórz stronę interfejsu HomeGraph API - Wybierz projekt pasujący do identyfikatora projektu w smart home.
- Kliknij WŁĄCZ.
Tworzenie klucza konta usługi
Aby wygenerować klucz konta usługi z Google Cloud Console, wykonaj te czynności:
-
W sekcji Google Cloud Console otwórz stronę Tworzenie klucza konta usługi.
Otwórz stronę Tworzenie klucza konta usługi - Z listy Konto usługi wybierz Nowe konto usługi.
- W polu Nazwa konta usługi wpisz nazwę.
- W polu Identyfikator konta usługi wpisz identyfikator.
Z listy Rola wybierz Konta usługi > Twórca tokenów konta usługi.
W polu Typ klucza wybierz opcję JSON.
- 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.
- 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.
- Uzyskaj token dostępu OAuth 2.0 z zakresem
https://www.googleapis.com/auth/homegraph
za pomocą oauth2l: - Utwórz żądanie JSON z atrybutem
agentUserId
. Oto przykładowe żądanie JSON dla stanu raportu i powiadomienia: - 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
:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
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
- Pobierz definicję usługi buforów protokołów dla interfejsu Home Graph API.
- Postępuj zgodnie z dokumentacją dla programistów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
- Wywołaj metodę ReportStateAndNotification.
Node.js
Klient Node.js interfejsów API Google dostarcza powiązania dla interfejsu API Home Graph.
- Zainicjuj usługę
google.homegraph
za pomocą domyślnych danych logowania aplikacji. - 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.
- Zainicjuj
HomeGraphApiService
za pomocą domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metodyReportStateAndNotificationRequest
. 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
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życienull
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 atrybutagentUserId
. Sprawdź, czyagentUserId
jest zgodna z wartością podaną w odpowiedzi SYNC i poprawnie obsługujesz intencje DISCONNECT.