Report State to ważna funkcja, dzięki której działanie Home może aktywnie zgłaszać najnowszy stan urządzenia użytkownika do Google Home Graph, zamiast czekać na działanie QUERY
.
Report State zgłasza Google stany urządzeń użytkowników z powiązanymi z nimi danymi 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 pobraniem intencji EXECUTE
przejrzeć informacje o stanie w Home Graph, zamiast wysyłać intencję QUERY
do różnych chmur innych firm.
Bez Report State, z powodu światła pochodzącego od wielu dostawców w salonie, polecenie OK Google, rozjaśnij salon wymaga przypisania wielu intencji QUERY
wysłanych do wielu chmur, a nie tylko sprawdzania bieżących wartości jasności na podstawie wcześniej zgłoszonych danych. Aby zapewnić użytkownikom jak najlepsze działanie, Assistant musi mieć obecny stan urządzenia, bez konieczności przesyłania go w obie strony.
Po wstępnym wywołaniu SYNC
przez urządzenie platforma wysyła intencję QUERY
, która zbiera informacje o stanie urządzenia, aby wypełnić Home Graph.
Po tym czasie Home Graph przechowuje tylko stan, który został wysłany za pomocą Report State.
Wywołując atrybut Report State, pamiętaj, aby podać pełne dane stanu dla danego atrybutu. Home Graph aktualizuje stany poszczególnych cech i zastępuje wszystkie dane tego atrybutu w momencie wywołania Report State. Jeśli na przykład raportujesz stan dla cechy StartStop, ładunek musi zawierać wartości zarówno dla isRunning
, jak i isPaused
.
Pierwsze kroki
Aby wdrożyć Report State, wykonaj te czynności:
Włącz Google HomeGraph API
-
W Google Cloud Platform Console przejdź na stronę HomeGraph API.
Otwórz stronę HomeGraph API - Wybierz projekt zgodny z identyfikatorem projektu smart home.
- Kliknij WŁĄCZ.
Tworzenie klucza konta usługi
Aby wygenerować klucz konta usługi z GCP Console:
-
W aplikacji GCP Console otwórz stronę Utwórz klucz konta usługi.
Otwórz stronę tworzenia 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 kont usługi.
W polu Typ klucza wybierz opcję JSON.
- Kliknij Utwórz. Plik JSON zawierający klucz pobrany na Twój komputer.
Wywoływanie interfejsu API
Wybierz opcję na poniższych kartach:
HTTP
Home Graph udostępnia punkt końcowy HTTP.
- Za pomocą pobranego pliku JSON konta usługi utwórz token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie przy użyciu 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
agentUserId
. Oto przykładowe żądanie JSON dotyczące stanu raportu i powiadomienia: - Połącz stan raportu i plik JSON powiadomienia oraz token z żądania POST w protokole HTTP z punktem końcowym Google Home Graph. Oto przykład, jak wykonać żądanie z poziomu wiersza poleceń
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 buforowania protokołu dla interfejsu Home Graph API.
- Postępuj zgodnie z dokumentacją dla deweloperów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
- Wywołaj metodę ReportStateAndNotification.
Node.js
Klient Node.js interfejsu Google API udostępnia powiązania dla interfejsu API Home Graph.
- Zainicjuj usługę
google.homegraph
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metody ReportStateAndNotificationRequest. Zwraca wartośćPromise
z atrybutem 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 udostępnia powiązania interfejsu Home Graph API.
- Zainicjuj aplikację
HomeGraphApiService
przy użyciu 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ć swoje działanie do uzyskania certyfikatu, przeprowadź test Report State.
Wymagania wstępne
Aby przetestować działanie, musisz mieć klucz konta usługi i agentUserId
. Jeśli masz już klucz konta usługi, agentUserId
i zobacz 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 panelu Report State.
Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami podanymi w dołączonym pliku README.MD
.
Po wdrożeniu panelu Report State otwórz panel 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 klucza konta
- Dodaj identyfikator UserAgent
Następnie kliknij Lista.
Wyświetli się lista wszystkich Twoich urządzeń. Po wypełnieniu listy możesz użyć przycisku Odśwież, aby zaktualizować stany urządzeń. W przypadku zmiany stanu urządzenia wiersz jest wyróżniony na zielono.
Odpowiedzi na błędy
Podczas wywoływania funkcji Report State możesz zobaczyć jedną z tych odpowiedzi na błędy. Te odpowiedzi mają postać kodów stanu HTTP.
400 Bad Request
– serwer nie może przetworzyć żądania wysłanego przez klienta z powodu nieprawidłowej składni. Częstą przyczyną jest zniekształcony kod JSON lub użycie wartościnull
zamiast „” w przypadku wartości ciągu znaków.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łowe żądanieagentUserId
. Sprawdź, czyagentUserId
pasuje do wartości w odpowiedzi SYNC i czy obsługujesz intencje DISCONNECT.