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

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

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

Без Report State , учитывая освещение от нескольких поставщиков в гостиной, команда «Окей, Google, увеличь мою гостиную» требует разрешения нескольких намерений 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 перейдите на страницу 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

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

HTTP

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 для состояния отчета и уведомления:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Объедините 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"
    

gRPC

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

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

Node.js

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

  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);
}
    

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

Рекомендуемые инструменты для этой задачи

Чтобы подготовить ваше действие к сертификации, важно протестировать Report State .

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

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

Панель мониторинга состояния отчета

Предварительные условия

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

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

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

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

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

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

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

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

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

Реакции на ошибки

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

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