Статус жалобы

Report State – важная функция, которая позволяет действию Google Homeпроактивно сообщать в 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, выполните следующие действия:

• Как включить Google HomeGraph API
• Как создать ключ сервисного аккаунта
• Вызов API

Как включить Google HomeGraph API

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

   Перейти на страницу HomeGraph API
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. В поле Key type (Тип ключа) выберите 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).execute();
}
    

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

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

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

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

Как создать отчет на панели мониторинга

Требования

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

Как развернуть сводку "Состояние отчетов"

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

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

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

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

• Выберите файл ключа аккаунта
• Как добавить agentUserId

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

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

Как сообщить о расхождении в отчете

Точность состояния на основе запросов показывает, насколько последнее состояние устройства в отчете соответствует его статусу, когда пользователь запрашивает информацию о нем. Ожидается, что это значение составит 99,5%. Чтобы узнать больше о текущем статусе точности отчетов о состоянии вашего проекта, ознакомьтесь со статьей Состояние устройств – точность отчетов о состоянии. Подробную информацию о журнале расхождений в статусе отчета можно посмотреть в интерфейсе просмотра журналов.

Вот пример журнала расхождений в статусе:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Определения полей журнала расхождений в отчетах о состоянии

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

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

400 Bad Request (Недопустимый запрос)

Сервер не смог обработать запрос, отправленный клиентом, из-за недопустимого синтаксиса. Распространенные причины: неправильный формат JSON или использование null вместо "" для строкового значения.

Ошибка 404: не найдено

Запрошенный ресурс не найден, но может быть доступен в будущем. Обычно это означает, что мы не можем найти запрошенное устройство. Также это может означать, что аккаунт пользователя не связан с Google или мы получили недействительный agentUserId. Убедитесь, что значение agentUserId совпадает со значением, указанным в ответе SYNC, и что вы правильно обрабатываете намерения DISCONNECT.

Если вызов ReportState завершается с ошибкой 404 NOT_FOUND, это означает, что облако и Home Graph не синхронизированы. Это может произойти, если устройство удалено из Home Graph или пользователь отменил связь аккаунта.

Чтобы устранить ошибки 404 в отчете о состоянии, выполните следующие действия:

1. Проверьте статус аккаунта пользователя. Вызовите devices.sync для agentUserId, который вернул ошибку 404. Это помогает определить, связана ли ошибка со всем аккаунтом пользователя или с определенным устройством.
   • Если при выполнении команды SYNC возвращается ошибка 404, значит аккаунт пользователя больше не связан с Google. Прекратите отправлять отчеты о состоянии и запросы на синхронизацию для устройств этого пользователя.
   • Если SYNC возвращает код 200 OK, аккаунт пользователя по-прежнему связан, а значит, ошибка 404 относится к определенному устройству.
2. Сопоставьте список устройств. Если SYNC возвращает код 200 OK, вам нужно определить, какие устройства больше не известны Google. Мы рекомендуем сравнить список устройств, которые есть у пользователя в Google, с вашей базой данных устройств и определить, какие устройства в вашей системе отсутствуют в списке Google. Если устройство должно быть синхронизировано с Google, но ещё не передано в Google, используйте SYNC, чтобы убедиться, что устройство синхронизировано с Google. Если устройство нужно отвязать от Google, прекратите передавать данные о его состоянии и продолжайте передавать данные о состоянии других устройств, связанных с agentUserId.

Отчеты о статусе онлайн и офлайн

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