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

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

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

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

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

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

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

Начать

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

Включить 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

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

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

Клиент 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);
}
    

Состояние отчета о тестировании

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

Чтобы подготовить действие к сертификации, важно протестировать 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

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

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

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

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

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

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

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