Powiadomienia o działaniach w inteligentnym domu

Powiadomienia umożliwiają integracji Cloud-to-cloud korzystanie z funkcji Google Assistant w celu informowania użytkowników o ważnych zdarzeniach lub zmianach związanych z urządzeniem. Możesz wdrażać powiadomienia, aby powiadamiać użytkowników o zdarzeniach związanych z urządzeniem, na przykład gdy ktoś stoi przy drzwiach, lub aby zgłaszać żądaną zmianę stanu urządzenia, na przykład gdy zamek w drzwiach został zablokowany lub zablokował się.

Integracja z Cloud-to-cloud może wysyłać użytkownikom te typy powiadomień:

  • Powiadomienia proaktywne: informują użytkownika o zdarzeniach na urządzeniu smart home bez wcześniejszych próśb użytkownika, takich jak dzwonek do drzwi.

  • Odpowiedzi na żądanie: potwierdzenie, że żądanie polecenia urządzenia zostało wykonane lub nie, na przykład w przypadku zamykania drzwi. Używaj tych alertów w przypadku poleceń dotyczących urządzenia, które wymagają czasu na wykonanie. Odpowiedzi na dalsze pytania są obsługiwane tylko wtedy, gdy żądania poleceń są wysyłane z inteligentnych głośników i inteligentnych ekranów.

Assistant wysyła te powiadomienia do użytkowników w postaci komunikatów na głośnikach i ekranach inteligentnych. Aktywne powiadomienia są domyślnie wyłączone. Użytkownicy mogą włączać i wyłączać wszystkie aktywne powiadomienia z Google Home app (GHA).

Zdarzenia wywołujące powiadomienia

Gdy występują zdarzenia na urządzeniu, usługa wysyła do Google żądanie powiadomienia. Cechy urządzenia obsługiwane przez integrację Cloud-to-cloudokreślają, jakie typy zdarzeń powiadomień są dostępne i jakie dane można uwzględnić w tych powiadomieniach.

Te cechy obsługują powiadomienia proaktywne:

Cecha Wydarzenia
ObjectDetection obiekty wykryte przez urządzenie, na przykład rozpoznana twarz przy drzwiach; Na przykład: "Alicja i Robert są przy drzwiach wejściowych."
RunCycle Urządzenie kończy cykl. Przykład: "Cykl pralki został zakończony."
SensorState Urządzenie wykryło obsługiwany stan czujnika. Na przykład: "Czujnik dymu wykrył dym."

Te cechy obsługują odpowiedzi uzupełniające:

Cecha Wydarzenia
LockUnlock stan po wykonaniu polecenia urządzenia action.devices.commands.LockUnlock. Na przykład: "Zamek w drzwiach wejściowych został zamknięty" lub "Drzwi wejściowe są zablokowane".
NetworkControl stan po wykonaniu polecenia urządzenia action.devices.commands.TestNetworkSpeed. Na przykład: „Test szybkości sieci już się zakończył. Szybkość pobierania na routerze w biurze to obecnie 80,2 Kbps, a szybkość wysyłania to 9,3 Kbps."
OpenClose stan po wykonaniu polecenia urządzenia action.devices.commands.OpenClose. Na przykład: "Drzwi wejściowe zostały otwarte" lub "Nie udało się otworzyć drzwi wejściowych".

Wszystkie typy urządzeń obsługują powiadomienia dotyczące odpowiednich cech.

Tworzenie powiadomień dla integracji z chmury do chmury

Dodaj powiadomienia do integracji Cloud-to-cloud na tych etapach:

  1. Powiadom Google, czy powiadomienia są włączone w aplikacji na urządzeniu smart home. Jeśli użytkownicy włączą lub wyłączą powiadomienia w aplikacji, wyślij SYNC, aby powiadomić Google o zmianie urządzenia.
  2. Gdy wystąpi odpowiednie zdarzenie lub zmiana stanu urządzenia, która powoduje wysłanie powiadomienia, wyślij żądanie powiadomienia, wywołując interfejs API Report State reportStateAndNotification. Jeśli stan urządzenia uległ zmianie, możesz wysłać zarówno stan, jak i dane ładunku powiadomienia w wywołaniu Report State i powiadomieniu.

W następnych sekcjach omawiamy te czynności bardziej szczegółowo.

Określ, czy powiadomienia są włączone w aplikacji

Użytkownicy mogą zdecydować, czy chcą otrzymywać proaktywne powiadomienia, włączając tę funkcję w sekcji GHA. W aplikacji na urządzeniesmart home możesz też opcjonalnie dodać możliwość włączania i wyłączania powiadomień na urządzeniu, na przykład w ustawieniach aplikacji.

Wskaż Google, że powiadomienia są włączone na Twoim urządzeniu, wysyłając wywołanie Request SYNC, aby zaktualizować dane urządzenia. Gdy użytkownicy zmieniają to ustawienie w aplikacji, powinieneś wysłać prośbę SYNC.

W odpowiedzi na SYNC prześlij jedną z tych informacji:

  • Jeśli użytkownik wyraźnie włączył powiadomienia w aplikacji na urządzeniu lub jeśli nie udostępniasz opcji przełącznika, ustaw właściwość devices.notificationSupportedByAgent na true.
  • Jeśli użytkownik wyraźnie wyłączył powiadomienia w aplikacji na urządzeniu, ustaw właściwość devices.notificationSupportedByAgent na false.

Ten fragment kodu pokazuje, jak ustawić odpowiedź SYNC:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Wysyłanie żądań powiadomień do Google

Aby wywołać powiadomienia w Assistant, usługa zapewniająca realizację wysyła do usługi Google Home Graph ładunek powiadomienia za pomocą wywołania interfejsu Report State i Notification 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.

Wysyłanie powiadomienia

Wywołaj żądanie powiadomienia za pomocą interfejsu API devices.reportStateAndNotification. Żądanie JSON musi zawierać parametr eventId, który jest unikalnym identyfikatorem wygenerowanym przez Twoją platformę dla zdarzenia, które wywołało powiadomienie. Wartość eventId powinna być losowym identyfikatorem, który jest inny za każdym razem, gdy wysyłasz żądanie powiadomienia.

W obiekcie notifications, który przekazujesz w wywołaniu interfejsu API, dołącz wartość priority, która określa sposób wyświetlania powiadomienia. Obiekt notifications może zawierać różne pola w zależności od urządzenia.

Aby ustawić ładunek i wywołać interfejs API, wykonaj jedną z tych czynności:

Wysyłanie aktywnego powiadomienia

Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:

HTTP

Interfejs API 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:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Utwórz żądanie JSON za pomocą agentUserId. Oto przykład żądania JSON dotyczącego Report State i powiadomienia:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. Połącz dane Report State i dane JSON powiadomienia oraz token w żądaniu HTTP POST do punktu końcowego Google Home Graph. Oto przykład żądania wysyłanego z poziomu wiersza poleceń za pomocą polecenia curl:
    5. 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 API Home Graph udostępnia punkt końcowy gRPC

  1. Pobierz definicję usługi protocol buffers dla interfejsu API Home Graph.
  2. Aby wygenerować atrapy klienta w jednym z obsługiwanych języków , postępuj zgodnie z dokumentacją dla deweloperów gRPC.
  3. Wywołaj metodę ReportStateAndNotification .

Node.js

Interfejsy Google API Node.js Client udostępniają 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',
    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 dla interfejsu Home Graph API.

  1. Inicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca ona 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);
Wysyłanie danych odpowiedzi na prośbę o dodatkowe informacje

Dane dotyczące odpowiedzi na żądanie zawierają stan żądania, kody błędów zdarzeń (jeśli występują) oraz prawidłowy obiekt followUpToken podany podczas żądania o zamiarach EXECUTE. Aby followUpToken pozostało ważne i odpowiednio powiązane z pierwotnym żądaniem, musisz użyć go w ciągu 5 minut.

Ten fragment kodu przedstawia 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, aby wyświetlać powiadomienie tylko na urządzeniu, z którym użytkownik pierwotnie się komunikował, a nie na wszystkich urządzeniach użytkownika.

Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:

HTTP

Interfejs API 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:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Utwórz żądanie JSON za pomocą agentUserId. Oto przykład żądania JSON dotyczącego Report State i powiadomienia:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. Połącz dane Report State i dane JSON powiadomienia oraz token w żądaniu HTTP POST do punktu końcowego Google Home Graph. Oto przykład żądania wysyłanego z poziomu wiersza poleceń za pomocą polecenia curl:
    5. 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 API Home Graph udostępnia punkt końcowy gRPC

  1. Pobierz definicję usługi protocol buffers dla interfejsu API Home Graph.
  2. Aby wygenerować atrapy klienta w jednym z obsługiwanych języków, postępuj zgodnie z dokumentacją dla deweloperów gRPC.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Interfejsy Google API Node.js Client udostępniają 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 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 dla interfejsu Home Graph API.

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

Logowanie

Powiadomienia obsługują rejestrowanie zdarzeń zgodnie z opisem w artykule Rejestrowanie zdarzeń w chmurze w przypadku przesyłania danych między usługami w chmurze. Te dzienniki są przydatne do testowania i utrzymywania jakości powiadomień w Twoim widżecie.

Oto schemat wpisu notificationLog:

Właściwość Opis
requestId Identyfikator prośby dotyczącej powiadomienia.
structName Nazwa struktury powiadomienia, np. „ObjectDetection”.
status Wskazuje stan powiadomienia.

Pole status zawiera różne stany, które mogą wskazywać na błędy w ładunku powiadomienia. Niektóre z nich mogą być dostępne tylko w przypadku działań, które nie zostały jeszcze wdrożone w wersji produkcyjnej.

Przykładowe stany:

Stan Opis
EVENT_ID_MISSING Oznacza, że brakuje wymaganego pola eventId.
PRIORITY_MISSING Wskazuje, że brakuje pola priority.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Wskazuje, że właściwość notificationSupportedByAgent urządzenia wysyłającego powiadomienie w tagu SYNC ma wartość false (fałsz).
NOTIFICATION_ENABLED_BY_USER_FALSE Wskazuje, że użytkownik nie włączył powiadomień na urządzeniu wysyłającym powiadomienia w ramach GHA. Ten stan jest dostępny tylko w przypadku integracji, które nie zostały wdrożone w wersji produkcyjnej.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Wskazuje, że użytkownik nie przypisał urządzenia wysyłającego powiadomienia do domu lub budynku. Ten stan jest dostępny tylko w przypadku integracji, które nie zostały wdrożone w wersji produkcyjnej.

Oprócz tych ogólnych stanów, które mogą dotyczyć wszystkich powiadomień, w polu status mogą też występować stany związane z cechami (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).

Wstecz
Wdróż stan raportu
Dalej
Testowanie integracji między chmurami