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

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 перейдите на страницу Service accounts (Сервисные аккаунты).

   Откройте страницу Сервисные аккаунты.

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

2. Нажмите addCreate service account (Создать сервисный аккаунт).

3. В поле Service account name (Название сервисного аккаунта) введите название.

4. В поле Service account ID (Идентификатор сервисного аккаунта) введите идентификатор.

5. В поле Service account description (Описание сервисного аккаунта) введите описание.

6. Нажмите кнопку Создать и продолжить.

7. В раскрывающемся списке Роль выберите Сервисные аккаунты > Создатель токенов идентификации OpenID Connect для сервисных аккаунтов.

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

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

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

11. Нажмите Add key (Добавить ключ) > Create new key (Создать ключ).

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

Получив ключ сервисного аккаунта и идентификатор пользователя агента для проекта, скачайте и разверните последнюю версию с панели управления 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, возвращаемые Report State, выполните следующие действия:

1. Проверьте статус аккаунта пользователя. Вызовите devices.sync для agentUserId, который вернул ошибку 404. Это поможет определить, связана ли ошибка со всем аккаунтом пользователя или с конкретным устройством.
   • Если SYNC возвращает ошибку 404, аккаунт пользователя больше не связан с Google. Прекратите отправлять Report State и Request Sync для устройств этого пользователя.
   • Если 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": {},
        }
      }
    }