Отчет о состоянии

Report State — важная функция, которая позволяет действию Google Home Action заблаговременно сообщать о последнем статусе устройства пользователя в Google Home Graph не дожидаясь намерения QUERY .

Report State сообщает Google о состояниях пользовательских устройств с указанным agentUserId , связанным с ними (отправленным в исходном запросе SYNC ). Когда Google Assistant хочет выполнить действие, требующее понимания текущего состояния устройства, он может просто посмотреть информацию о состоянии в Home Graph вместо того, чтобы выдавать намерение QUERY различным сторонним облакам перед выдачей намерения EXECUTE .

Без Report State , учитывая, что в гостиной есть свет от нескольких поставщиков, команда Ok Google, brighten my living room требует разрешения нескольких намерений QUERY , отправленных в несколько облаков, в отличие от простого поиска текущих значений яркости на основе того, что было сообщено ранее. Для лучшего пользовательского опыта Assistant должен иметь текущее состояние устройства, не требуя кругового обхода устройства.

После первоначальной SYNC для устройства платформа отправляет намерение QUERY , которое собирает состояние устройства для заполнения Home Graph . После этого момента Home Graph сохраняет только состояние, отправленное с помощью Report State .

При вызове Report State обязательно укажите полные данные о состоянии для данного признака. Home Graph обновляет состояния по каждому признаку и перезаписывает все данные для этого признака при вызове Report State . Например, если вы сообщаете о состоянии для признака StartStop , полезная нагрузка должна включать значения как для isRunning , так и isPaused .

Начать

Чтобы реализовать Report State , выполните следующие действия:

• Включить API Google HomeGraph
• Создать ключ учетной записи службы
• Вызов API

Включить API Google HomeGraph

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

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

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

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

1. В Google Cloud Console перейдите на страницу учетных записей служб .

   Перейдите на страницу «Учетные записи служб» .

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

2. Нажмите « add Создать учетную запись службы .

3. В поле Имя учетной записи службы введите имя.

4. В поле «Идентификатор учетной записи службы» введите идентификатор.

5. В поле Описание учетной записи службы введите описание.

6. Нажмите «Создать» и продолжите .

7. В раскрывающемся списке «Роль» выберите «Учетные записи служб» > «Создатель токена удостоверения OpenID Connect для учетной записи службы» .

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

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

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

11. Выберите Добавить ключ > Создать новый ключ .

12. Для типа ключа выберите опцию JSON .

13. Нажмите «Создать» . Файл JSON, содержащий ваш ключ, загрузится на ваш компьютер.

Вызов API

Выберите вариант на вкладках ниже:

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',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

  // 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 state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request);
}
    

Состояние отчета об испытаниях

Чтобы подготовить вашу интеграцию Cloud-to-cloud к сертификации, важно протестировать Report State .

Для этого мы рекомендуем использовать инструмент Home Graph Viewer, представляющий собой автономное веб-приложение, не требующее загрузки или развертывания.

Панель мониторинга Report State по-прежнему доступна, но устарела и больше не поддерживается.

Отчет о состоянии панели мониторинга

Предпосылки

Прежде чем вы сможете протестировать интеграцию Cloud-to-cloud , вам понадобятся ключ учетной записи службы и ваш agentUserId . Если у вас уже есть ключ учетной записи службы и agentUserId , см. Развертывание панели мониторинга Report State .

Разверните панель мониторинга состояния отчета

После того, как у вас есть ключ учетной записи службы и идентификатор пользователя агента для вашего проекта, загрузите и разверните последнюю версию из Report State Dashboard . После загрузки последней версии следуйте инструкциям из прилагаемого файла README.MD .

После развертывания панели мониторинга Report State откройте ее по следующему URL-адресу (замените your_project_id на идентификатор вашего проекта):

http://<your-project-id>.appspot.com

На панели управления выполните следующие действия:

• Выберите файл ключа вашего аккаунта
• Добавьте свой идентификатор пользователя агента

Затем нажмите «Список» .

Все ваши устройства перечислены. После заполнения списка вы можете использовать кнопку «Обновить» , чтобы обновить состояния устройств. Если состояние устройства изменилось, строка выделяется зеленым цветом.

Отчет о несоответствии состояния

Точность состояния отчета на основе запроса измеряет, насколько хорошо последнее состояние отчета для устройства соответствует статусу устройства, когда пользователь запрашивает его. Ожидается, что это значение составит 99,5%.

Ответы об ошибках

Вы можете получить один из следующих ответов об ошибке при вызове Report State . Эти ответы приходят в виде кодов состояния HTTP.

• 400 Bad Request — сервер не смог обработать запрос, отправленный клиентом, из-за недопустимого синтаксиса . Распространенные причины включают в себя некорректный JSON или использование null вместо "" для строкового значения.
• 404 Not Found — запрошенный ресурс не найден, но может быть доступен в будущем. Обычно это означает, что мы не можем найти запрошенное устройство. Это также может означать, что учетная запись пользователя не связана с Google или мы получили недействительный agentUserId . Убедитесь, что agentUserId соответствует значению, указанному в вашем ответе SYNC , и вы правильно обрабатываете намерения DISCONNECT .

Онлайн и офлайн отчетность о состоянии

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }