Уведомления о действиях для умного дома

Уведомления позволяют интеграции Cloud-to-cloud использовать Google Assistant, чтобы сообщать пользователям о важных событиях или изменениях, связанных с устройствами. Вы можете настроить уведомления, чтобы сообщать пользователям о событиях, связанных с устройствами, например о том, что кто-то стоит у двери, или об изменении состояния устройства, например о том, что замок успешно заперт или заклинил.

Интеграция с Cloud-to-cloud позволяет отправлять пользователям следующие типы уведомлений:

  • Умные уведомления. Оповещают пользователя о событии на устройстве smart home без предварительного запроса, например о звонке в дверь.

  • Ответы на запросы. Подтверждение того, что команда устройства выполнена успешно или нет, например при запирании двери. Используйте эти оповещения для команд, выполнение которых занимает много времени. Ответы на уточняющие вопросы поддерживаются, только если запросы на выполнение команд отправляются с умных колонок и дисплеев.

Assistant отправляет пользователям эти уведомления в виде объявлений на умных колонках и умных дисплеях. Умные уведомления отключены по умолчанию. Пользователи могут включать и отключать все умные уведомления в Google Home app (GHA).

События, которые активируют уведомления

Когда на устройстве происходит событие, ваш сервис отправляет запрос на уведомление в Google. Типы событий уведомлений и данные, которые можно в них включать, зависят от характеристик устройств, поддерживаемых вашей интеграцией Cloud-to-cloud.

Умные уведомления поддерживаются для следующих функций:

Черта характера События
ObjectDetection Объекты, обнаруженные устройством, например когда у двери распознано знакомое лицо. Пример: "Алиса и Иван у входной двери".
RunCycle Устройство завершает цикл. Пример: "Стирка завершена".
SensorState Устройство обнаружило поддерживаемое состояние датчика. Пример: "Датчик дыма обнаружил дым".

Следующие характеристики поддерживают последующие ответы:

Черта характера События
LockUnlock Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.LockUnlock. Например, "Входная дверь заперта" или "Входную дверь заклинило".
NetworkControl Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.TestNetworkSpeed. Пример: "Тест скорости сети завершен. Скорость скачивания на офисном маршрутизаторе сейчас составляет 80,2 кбит/с, а скорость загрузки – 9,3 кбит/с.
OpenClose Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.OpenClose. Например, "Входная дверь открыта" или "Не удалось открыть входную дверь".

Все типы устройств поддерживают уведомления для соответствующих функций.

Как создать уведомления для облачной интеграции

Добавьте уведомления в интеграцию Cloud-to-cloud на следующих этапах:

  1. Сообщите Google, включены ли уведомления в вашем smart home приложении устройства. Если пользователи включают или отключают уведомления в вашем приложении, отправьте запрос SYNC, чтобы сообщить Google об изменении устройства.
  2. Когда происходит событие или изменение состояния устройства, которое должно вызвать уведомление, отправьте запрос на уведомление, вызвав API Report State reportStateAndNotification. Если состояние устройства изменилось, вы можете отправить полезную нагрузку состояния и уведомления вместе в вызове Report State и Notification.

Ниже вы найдете подробное описание этих шагов.

Укажите, включены ли уведомления в вашем приложении

Пользователи могут включить или отключить умные уведомления в GHA. В приложении для устройства smart home вы также можете добавить возможность для пользователей явно переключать уведомления с устройства, например, в настройках приложения.

Сообщите Google, что уведомления включены, выполнив вызов Request SYNC для обновления данных устройства. Запрос SYNC следует отправлять каждый раз, когда пользователь меняет эту настройку в приложении.

В ответе SYNC отправьте одно из следующих обновлений:

  • Если пользователь включил уведомления в приложении устройства или вы не добавили переключатель, задайте для свойства devices.notificationSupportedByAgent значение true.
  • Если пользователь явно отключил уведомления в приложении устройства, задайте для свойства devices.notificationSupportedByAgent значение false.

В следующем фрагменте кода показано, как настроить ответ SYNC:

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

Отправка запросов на уведомления в Google

Чтобы активировать уведомления на устройстве Assistant, ваш сервис отправляет полезную нагрузку уведомления в Google Home Graph с помощью вызова Report State и Notification API.

Включите Google HomeGraph API

  1. В Google Cloud Console перейдите на страницу HomeGraph API.

    Перейти на страницу HomeGraph API
  2. Выберите проект, соответствующий вашему идентификатору проекта smart home.
  3. Нажмите Включить.

Как создать ключ сервисного аккаунта

Чтобы создать ключ сервисного аккаунта в Google Cloud Console, выполните следующие действия:

Примечание. При выполнении этих действий убедитесь, что вы используете правильный проект GCP. Это проект, который соответствует вашему идентификатору проекта smart home.
  1. В Google Cloud Console перейдите на страницу Service accounts (Сервисные аккаунты).

    Откройте страницу Сервисные аккаунты.

    Возможно, вам потребуется выбрать проект, прежде чем вы перейдете на страницу сервисных аккаунтов.

  2. Нажмите Создать сервисный аккаунт.

  3. В поле Service account name (Название сервисного аккаунта) введите название.

  4. В поле Service account ID (Идентификатор сервисного аккаунта) введите идентификатор.

  5. В поле Service account description (Описание сервисного аккаунта) введите описание.

  6. Нажмите кнопку Создать и продолжить.

  7. В раскрывающемся списке Role (Роль) выберите Service Accounts (Сервисные аккаунты) > Service Account OpenID Connect Identity Token Creator (Создатель токена идентификации OpenID Connect для сервисного аккаунта).

  8. Нажмите Продолжить.

  9. Нажмите Готово.

  10. Выберите созданный сервисный аккаунт из списка и в меню Действия нажмите Управление ключами.

  11. Нажмите Add key (Добавить ключ) > Create new key (Создать ключ).

  12. В поле Key type (Тип ключа) выберите JSON.

  13. Нажмите Создать. На компьютер будет скачан JSON-файл с ключом.

Подробные инструкции и информацию о создании ключей сервисных аккаунтов можно найти в статье Как создавать и удалять ключи сервисных аккаунтов на сайте справки консоли Google Cloud.

Отправьте уведомление

Вызовите запрос уведомления с помощью API devices.reportStateAndNotification. Ваш JSON-запрос должен содержать eventId – уникальный идентификатор, созданный вашей платформой для события, которое активирует уведомление. Значение eventId должно быть случайным идентификатором, который меняется при каждом запросе уведомления.

В объекте notifications, который вы передаете в вызове API, укажите значение priority, определяющее, как должно быть представлено уведомление. Объект notifications может включать разные поля в зависимости от типа устройства.

Чтобы задать полезную нагрузку и вызвать API, выполните одно из следующих действий:

Отправка полезной нагрузки для упреждающего уведомления

Чтобы вызвать API, выберите один из вариантов на вкладках ниже.

HTTP

API Home Graph предоставляет конечную точку HTTP,

  1. Используйте скачанный JSON-файл сервисного аккаунта, чтобы создать веб-токен JSON (JWT). Подробнее об аутентификации с помощью сервисного аккаунта…
  2. Получите токен доступа OAuth 2.0 с областью действия https://www.googleapis.com/auth/homegraph, используя oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Создайте запрос JSON с помощью agentUserId. Ниже приведен пример запроса JSON для Report State и уведомления.
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. Объедините JSON-код Report State и уведомления, а также токен в HTTP-запросе POST к конечной точке Google Home Graph. Вот пример того, как можно сделать запрос в командной строке с помощью curl:
  7. 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 API предоставляет конечную точку gRPC.

  1. Получите определение сервиса буферов протокола для Home Graph API.
  2. Следуйте инструкциям в документации для разработчиков gRPC, чтобы создать заглушки клиента для одного из поддерживаемых языков.
  3. Вызовите метод ReportStateAndNotification.

Node.js

Клиент Node.js для API Google предоставляет привязки для Home Graph API.

  1. Инициализируйте сервис google.homegraph, используя Application Default Credentials.
  2. Вызовите метод reportStateAndNotification с ReportStateAndNotificationRequest. Возвращает Promise с 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

Клиентская библиотека HomeGraph API для Java предоставляет привязки для API Home Graph.

  1. Инициализируйте HomeGraphApiService, используя Application Default Credentials.
  2. Вызовите метод reportStateAndNotification с ReportStateAndNotificationRequest. Возвращает 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);
    
Как отправить полезную нагрузку последующего ответа

Полезная нагрузка для последующего ответа содержит статус запроса, коды ошибок для сбоев событий, если применимо, и действительный followUpToken, предоставленный во время запроса намерения EXECUTE. Чтобы ответ был правильно сопоставлен с исходным запросом, followUpToken нужно использовать в течение пяти минут.

Ниже приведен пример полезной нагрузки запроса EXECUTE с полем 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 использует followUpToken, чтобы уведомление появлялось только на том устройстве, с которым пользователь взаимодействовал изначально, а не на всех его устройствах.

Чтобы вызвать API, выберите один из вариантов на вкладках ниже.

HTTP

API Home Graph предоставляет конечную точку HTTP,

  1. Используйте скачанный JSON-файл сервисного аккаунта, чтобы создать веб-токен JSON (JWT). Подробнее об аутентификации с помощью сервисного аккаунта…
  2. Получите токен доступа OAuth 2.0 с областью действия https://www.googleapis.com/auth/homegraph, используя oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Создайте запрос JSON с помощью agentUserId. Ниже приведен пример запроса JSON для Report State и уведомления.
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. Объедините JSON-код Report State и уведомления, а также токен в HTTP-запросе POST к конечной точке Google Home Graph. Вот пример того, как можно сделать запрос в командной строке с помощью curl:
  7. 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 API предоставляет конечную точку gRPC.

  1. Получите определение сервиса буферов протокола для Home Graph API.
  2. Следуйте инструкциям в документации для разработчиков gRPC, чтобы сгенерировать заглушки клиента для одного из поддерживаемых языков.
  3. Вызовите метод ReportStateAndNotification.

Node.js

Клиент Node.js для API Google предоставляет привязки для Home Graph API.

  1. Инициализируйте сервис google.homegraph, используя Application Default Credentials.
  2. Вызовите метод reportStateAndNotification с ReportStateAndNotificationRequest. Возвращает Promise с 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

Клиентская библиотека HomeGraph API для Java предоставляет привязки для API Home Graph.

  1. Инициализируйте HomeGraphApiService, используя Application Default Credentials.
  2. Вызовите метод reportStateAndNotification с ReportStateAndNotificationRequest. Возвращает объект 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);
    

Журналы

Уведомления поддерживают ведение журнала событий, как описано в статье Ведение журнала Cloud для облачных интеграций. Эти журналы полезны для тестирования и поддержания качества уведомлений в вашем Действии.

Ниже приведена схема записи notificationLog:

Свойство Описание
requestId Идентификатор запроса на уведомление.
structName Название структуры уведомления, например ObjectDetection.
status Статус уведомления.

Поле status содержит различные статусы, которые могут указывать на ошибки в полезной нагрузке уведомления. Некоторые из них могут быть доступны только для действий, которые не были запущены в производство.

Возможные статусы:

Статус Описание
EVENT_ID_MISSING Указывает, что отсутствует обязательное поле eventId.
PRIORITY_MISSING Указывает, что отсутствует поле priority.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Указывает, что свойство notificationSupportedByAgent устройства, отправляющего уведомление, указанное в SYNC, имеет значение false.
NOTIFICATION_ENABLED_BY_USER_FALSE Указывает, что пользователь не включил уведомления на устройстве, отправляющем уведомления, в GHA. Этот статус доступен только для интеграций, которые не были запущены в рабочей среде.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Указывает, что пользователь не назначил устройство, отправляющее уведомления, дому или структуре. Этот статус доступен только для интеграций, которые не были запущены в рабочей среде.

Помимо этих общих статусов, которые могут применяться ко всем уведомлениям, поле status может также включать статусы, относящиеся к конкретным признакам (например, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).