Добро пожаловать в Центр разработчиков Google Home, новое место, где можно научиться разрабатывать действия для умного дома. Примечание. Вы продолжите создавать действия в консоли действий.

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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Уведомления позволяют вашему 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.

Ваш smart home Action может отправлять пользователям следующие типы уведомлений:

  • Упреждающие уведомления : оповещает пользователя о событии устройства « smart home » без каких-либо предварительных пользовательских запросов к своим устройствам, например, о звонке в дверь.

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

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

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

Когда происходят события на устройстве, выполнение вашего действия отправляет запрос на уведомление в Google. Характеристики устройства, которые поддерживает действие вашего smart home , определяют, какие типы событий уведомлений доступны, а также данные, которые вы можете включать в эти уведомления.

Следующие трейты поддерживают упреждающие уведомления:

Черта События
Обнаружение объектов Объекты, обнаруженные устройством, например, обнаружение распознанного лица у двери. Например: «Алиса и Боб стоят у входной двери».
RunCycle Устройство завершает цикл. Например: «Цикл стиральной машины завершен».
СенсорСтате Устройство обнаруживает поддерживаемое состояние датчика. Например: «Детектор дыма обнаруживает дым».

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

Черта События
ЗаблокироватьРазблокировать Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.LockUnlock . Например: «Входная дверь была заперта» или «Входная дверь заблокирована».
Сетевой контроль Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.TestNetworkSpeed . Например: «Ваш тест скорости сети завершен. Скорость загрузки на офисном маршрутизаторе в настоящее время составляет 80,2 Кбит/с, а скорость загрузки — 9,3 Кбит/с».
Открыто закрыто Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.OpenClose . Например: «Входная дверь открылась» или «Входная дверь не может быть открыта».

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

Создание уведомлений для вашего умного дома Действие

Добавьте уведомления в свой smart home Действия на этих этапах:

  1. Сообщите Google, включены ли уведомления в приложении для smart home . Если пользователи включают или выключают уведомления в вашем приложении, отправьте запрос SYNC , чтобы сообщить Google об изменении устройства.
  2. Когда происходит соответствующее событие устройства или изменение состояния, которое инициирует уведомление, отправьте запрос на уведомление, вызвав 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.

В следующих разделах эти шаги рассматриваются более подробно.

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

Пользователи могут выбрать, хотят ли они получать проактивные уведомления, включив эту функцию в 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 via a Report State and Notification API call .

Включить Google HomeGraph API

  1. В Google Cloud Platform Console , go to the HomeGraph API page.

    Перейдите на страницу API HomeGraph.
  2. Выберите проект, который соответствует вашему идентификатору проекта smart home .
  3. Щелкните ВКЛЮЧИТЬ .

Создайте ключ служебной учетной записи

Следуйте этим инструкциям, чтобы сгенерировать ключ учетной записи службы из GCP Console :

Примечание . При выполнении этих шагов убедитесь, что вы используете правильный проект GCP. Это проект, который соответствует вашему идентификатору проекта smart home .
  1. В GCP Console перейдите на страницу « Создать ключ сервисной учетной записи ».

    Перейдите на страницу создания ключа сервисной учетной записи.
  2. В списке Учетная запись службы выберите Новая учетная запись службы .
  3. В поле Имя учетной записи службы введите имя.
  4. В поле Идентификатор учетной записи службы введите идентификатор.
  5. В списке Роли выберите Учетные записи служб > Создатель токена учетной записи службы .

  6. Для Типа ключа выберите параметр JSON .

  7. Щелкните Создать . Файл JSON, содержащий ваш ключ, загружаемый на ваш компьютер.

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

Выполните вызов запроса уведомления с помощью 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

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

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

Node.js

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

  1. Инициализируйте службу google.homegraph , используя учетные данные приложения по умолчанию .
  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
              }
            }
          }
        }
      }
    }
  }
});
    

Джава

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

  1. Инициализируйте HomeGraphApiService используя учетные данные приложения по умолчанию .
  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

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

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

Node.js

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

  1. Инициализируйте службу google.homegraph , используя учетные данные приложения по умолчанию .
  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,
              }
            }
          }
        }
      }
    }
  }
});
    

Джава

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

  1. Инициализируйте HomeGraphApiService используя учетные данные приложения по умолчанию
  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);
    

Ведение журнала

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

Ниже приведена схема записи в журнале 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 ).