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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вызов API

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

HTTP

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

  1. Используйте загруженный файл JSON учетной записи службы для создания JSON Web Token (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 and Notification:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
  6. Объедините Report State and Notification JSON и токен в вашем 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"
    

гРПЦ

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

Ява

Клиентская библиотека 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 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 .

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

Если устройство находится в автономном режиме, вы должны сообщить об этом для отчета о состоянии в течение пяти минут поведения устройства. И наоборот, когда устройство возвращается в состояние онлайн, вы должны сообщить для отправки отчета о состоянии в течение пяти минут после изучения поведения устройства. Всякий раз, когда устройство возвращается в онлайн, партнер должен сообщать все текущие состояния устройства с помощью API reportStateAndNotification . Этот пример показывает, что тип устройства light находится в онлайне и сообщает все текущие состояния устройства.
"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }