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

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

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

Ваш 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. Когда происходит соответствующее событие устройства или изменение состояния, которое инициирует уведомление, отправьте запрос на уведомление, вызвав 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 and Notification API .

Включить Google HomeGraph API

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

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

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

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

Примечание . При выполнении этих шагов убедитесь, что вы используете правильный проект GCP. Это проект, который соответствует вашему идентификатору проекта smart home .
  1. В Google Cloud 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 ).