Dzięki powiadomieniom smart home Action to use Google Assistant to communicate with users about important device-related events or changes. You can implement notifications to alert users to timely device events, for example when someone is at the door, or to report on a requested device state change, such as when a door lock bolt has been successfully engaged or has jammed.
Akcja smart home może wysyłać do użytkowników te rodzaje powiadomień:
Aktywne powiadomienia: powiadamia użytkownika o zdarzeniu związanym z urządzeniem smart home bez wcześniejszego wysyłania do niego żądań, takich jak dzwonek.
Dalsze odpowiedzi: potwierdzenie, że polecenie urządzenia zakończyło się powodzeniem lub niepowodzeniem, na przykład zamknięcie drzwi. Używaj tych alertów do wykonywania poleceń na urządzeniu, którego wykonanie zajmuje dużo czasu. Kolejne odpowiedzi są obsługiwane tylko wtedy, gdy żądania dotyczące poleceń urządzenia są wysyłane z inteligentnych głośników i inteligentnych ekranów.
Assistant wysyła do użytkowników te powiadomienia w formie ogłoszeń na inteligentnych głośnikach i inteligentnych ekranach. Aktywne powiadomienia są domyślnie wyłączone. Użytkownicy mogą włączać i wyłączać wszystkie aktywne powiadomienia z Google Home app (GHA).
Zdarzenia, które powodują wyświetlanie powiadomień
W chwili wystąpienia zdarzeń na urządzeniu Realizacja działania wysyła powiadomienie do Google. Cechy urządzenia obsługiwane przez działanie smart home określają, jakie typy zdarzeń powiadomień są dostępne i jakie dane mogą być zawarte w tych powiadomieniach.
Usługi te mają proaktywne powiadomienia:
Kasa | Zdarzenia |
---|---|
Wykrywanie obiektów | Obiekty wykryte przez urządzenie, na przykład wykryte przez drzwi. Na przykład: „Alicja i Robert są przed drzwiami”. |
RunCycle | Urządzenie kończy cykl. Na przykład: „Cykl pralki zakończył się”. |
Stan czujnika | Urządzenie wykrywa obsługiwany stan czujnika. Na przykład: „Czujnik dymu wykrył dym”. |
Sterowanie temperaturą | Urządzenie osiągnie nastawę temperatury. Na przykład: „piekarnik został podgrzany do 350 stopni”. |
AlarDisarm | System przechodzi w stan wstępnego alarmu z odliczaniem wejściowym, które jest aktywowane przez otwarte drzwi. |
Transmisja z kamery | Link do transmisji na żywo z kamery po wykryciu przez urządzenie obiektu lub ruchu. |
MotionDetect | „1 lipca 2020 r. o 12:00 wykryto ruch”. |
Te cechy obsługują dalsze odpowiedzi:
Kasa | Zdarzenia |
---|---|
AlarDisarm | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.ArmDisarm . Na przykład: „System alarmowy został włączony”.
|
blokada | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.LockUnlock . Na przykład: „drzwi frontowe zostały zablokowane” lub „drzwi frontowe zostały zablokowane”.
|
Sterowaniesiecią | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.TestNetworkSpeed . Na przykład: „Twój test szybkości sieci zakończył się. Szybkość pobierania na routerze w biurze to obecnie 80,2 kb/s, a szybkość wysyłania wynosi 9,3 kb/s”.
|
OpenClose | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.OpenClose . Na przykład: „Nie udało się otworzyć drzwi wejściowych” lub „Nie udało się otworzyć drzwi wejściowych”.
|
StartStop | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.StartStop . Na przykład: „Odkurzacz został uruchomiony”.
|
Wszystkie typy urządzeń obsługują powiadomienia dotyczące określonych cech.
Tworzenie powiadomień dotyczących inteligentnego działania domu
Dodaj powiadomienia do działania smart home w tych etapach:
- Poinformuj Google, czy powiadomienia z aplikacji smart home są włączone. Jeśli użytkownicy włączyli lub wyłączyli powiadomienia w Twojej aplikacji, wyślij do
SYNC
prośbę o zmianę urządzenia. - Gdy nastąpi odpowiednie zdarzenie na urządzeniu lub zmiana stanu, które powoduje wysłanie powiadomienia, wyślij żądanie powiadomienia, wywołując Report State
reportStateAndNotification
API. If the device state changed, you can send both a state and notification payload together in your Report State and Notification call.
Poniżej znajdziesz szczegółowe omówienie tych czynności.
Określ, czy w aplikacji są włączone powiadomienia
Użytkownicy mogą określić, czy chcą otrzymywać aktywne powiadomienia, włączając tę funkcję w GHA. W aplikacji przeznaczonej dla urządzenia z smart home możesz też opcjonalnie włączyć opcję jawnego przełączania powiadomień z urządzenia przez użytkownika, na przykład w ustawieniach aplikacji.
Poinformuj Google, że na Twoim urządzeniu są włączone powiadomienia, wywołując opcję Poproś o synchronizację, aby zaktualizować dane urządzenia. Wyślij takie żądanie SYNC
za każdym razem, gdy użytkownik zmieni to ustawienie w Twojej aplikacji.
W odpowiedzi SYNC
wyślij jedną z tych zmian:
- Jeśli użytkownik wyraźnie przełączył powiadomienia w aplikacji na urządzeniu lub jeśli nie widzisz opcji przełączania, ustaw właściwość
devices.notificationSupportedByAgent
natrue
. - Jeśli użytkownik wyraźnie wyłączył powiadomienia w aplikacji na urządzeniu, ustaw właściwość
devices.notificationSupportedByAgent
nafalse
.
Fragment kodu poniżej pokazuje, jak ustawić odpowiedź SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Wysyłaj żądania powiadomień do Google
Aby aktywować powiadomienia w Assistant, Twoja realizacja wysyła ładunek powiadomień do Google Home Graph via a Report State and Notification API call..
Włącz Google HomeGraph API
-
W tunelu – Google Cloud Console, go to the HomeGraph API page.
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 Google Cloud Console:
-
W aplikacji Google Cloud 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.
Wyślij powiadomienie
Wywołaj żądanie powiadomienia za pomocą interfejsu API devices.reportStateAndNotification
.
Żądanie JSON musi zawierać eventId
, czyli unikalny identyfikator generowany przez platformę dla zdarzenia wywołującego powiadomienie. eventId
powinien być losowym identyfikatorem, który różni się za każdym razem, gdy wysyłasz żądanie powiadomienia.
W obiekcie notifications
przekazywanym w wywołaniu interfejsu API podaj wartość priority
, która określa, jak powinno wyglądać powiadomienie. Obiekt notifications
może zawierać różne pola w zależności od cech urządzenia.
Aby ustawić ładunek i wywołać interfejs API, wykonaj jedną z tych czynności:
Wyślij aktywny ładunek powiadomień
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs Home Graph API 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 dla Report State i Powiadomienie: - Połącz Report State oraz JSON powiadomienia i 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
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "ObjectDetection": { "priority": 0, "detectionTimestamp": 1534875126750, "objects": { "named": [ "Alice" ], "unclassified": 2 } } } } } } }
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
Interfejs Home Graph API udostępnia punkt końcowy gRPC.
- Pobierz definicję usługi buforów protokołów dla interfejsu API Home Graph.
- 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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { ObjectDetection: { priority: 0, detectionTimestamp: 1534875126750, objects: { named: ['Alice'], unclassified: 2 } } } } } } } });
Java
Biblioteka klienta interfejsu HomeGraph API dla języka Java udostępnia powiązania Home Graph interfejsu 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 notification payload. Map<?, ?> notifications = Map.of( "ObjectDetection", Map.of( "priority", 0, "detectionTimestamp", 1534875126, "objects", Map.of("named", List.of("Alice"), "unclassifed", 2))); // Send notification. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications)))); homegraphService.devices().reportStateAndNotification(request);
Wyślij ładunek odpowiedzi uzupełniającej
Ładunek dla odpowiedzi uzupełniającej zawiera stan żądania, kody błędów awarii (w stosownych przypadkach) i prawidłowy nagłówek followUpToken
podany w żądaniu intencji EXECUTE
. followUpToken
musi zostać użyty w ciągu 5 minut, aby zachować ważność i prawidłowo powiązać odpowiedź z pierwotnym żądaniem.
Fragment kodu poniżej pokazuje przykładowy ładunek żądania EXECUTE
z polem followUpToken
.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123", }], "execution": [{ "command": "action.devices.commands.TestNetworkSpeed", "params": { "testDownloadSpeed": true, "testUploadSpeed": false, "followUpToken": "PLACEHOLDER" } }] }] } }] };
Google używa followUpToken
do wyświetlania powiadomień tylko na urządzeniu, z którym użytkownik pierwotnie skontaktował się, a nie na inne urządzenia.
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs Home Graph API 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 dla Report State i Powiadomienie: - Połącz Report State oraz JSON powiadomienia i 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
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "NetworkControl": { "priority": 0, "followUpResponse": { "status": "SUCCESS", "followUpToken": "PLACEHOLDER", "networkDownloadSpeedMbps": 23.3, "networkUploadSpeedMbps": 10.2 } } } } } } }
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
Interfejs Home Graph API udostępnia punkt końcowy gRPC.
- Pobierz definicję usługi buforów protokołów dla interfejsu API Home Graph.
- 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 followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken; 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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { NetworkControl: { priority: 0, followUpResponse: { status: 'SUCCESS', followUpToken, networkDownloadSpeedMbps: 23.3, networkUploadSpeedMbps: 10.2, } } } } } } } });
Java
Biblioteka klienta interfejsu HomeGraph API dla języka Java udostępnia powiązania Home Graph interfejsu API.
- Inicjowanie
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(); // Extract follow-up token. ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0]; String followUpToken = (String) executeInputs .getPayload() .getCommands()[0] .getExecution()[0] .getParams() .get("followUpToken"); // Build device follow-up response payload. Map<?, ?> followUpResponse = Map.of( "NetworkControl", Map.of( "priority", 0, "followUpResponse", Map.of( "status", "SUCCESS", "followUpToken", followUpToken, "networkDownloadSpeedMbps", 23.3, "networkUploadSpeedMbps", 10.2))); // Send follow-up response. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse)))); homegraphService.devices().reportStateAndNotification(request);
Logging
Powiadomienia obsługują logowanie zdarzeń zgodnie z opisem w artykule Dostęp do dzienników zdarzeń za pomocą Cloud Logging. Logi te są przydatne podczas testowania i utrzymywania wysokiej jakości powiadomień w działaniu.
Oto schemat wpisu notificationLog
:
Właściwość | Opis |
---|---|
requestId |
Identyfikator żądania powiadomienia. |
structName |
Nazwa struktury powiadomień, na przykład „ObjectDetection”. |
status |
Określa stan powiadomienia. |
Pole status
zawiera różne stany, które mogą wskazywać na błędy w ładunku powiadomień. Niektóre z nich mogą być dostępne tylko w akcjach, które nie zostały jeszcze uruchomione w środowisku produkcyjnym.
Przykładowe stany:
Stan | Opis |
---|---|
EVENT_ID_MISSING |
Brakuje wymaganego pola eventId .
|
PRIORITY_MISSING |
Oznacza, że brakuje pola priority .
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Wskazuje, że właściwość notificationSupportedByAgent urządzenia zgłaszającego podana w polu SYNC jest nieprawidłowa.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Wskazuje, że użytkownik nie włączył powiadomień na urządzeniu, które wysyła powiadomienia: GHA. Ten stan jest dostępny tylko w działaniach, które nie zostały jeszcze uruchomione w wersji produkcyjnej. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Wskazuje, że użytkownik nie przypisał urządzenia do powiadomień do domu/struktury. Ten stan jest dostępny tylko w działaniach, które nie zostały jeszcze uruchomione w wersji produkcyjnej. |
Oprócz stanów ogólnych, które mogą być stosowane do wszystkich powiadomień, pole status
może też uwzględniać informacje o określonych cechach (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).