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

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

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

    Перейти на страницу HomeGraph API
  2. Выберите проект, соответствующий вашему идентификатору проекта smart home.
  3. Нажмите Включить.

Как создать ключ сервисного аккаунта

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

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

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

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

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

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

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

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

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

  7. В раскрывающемся списке Role (Роль) выберите Service Accounts (Сервисные аккаунты) > Service Account OpenID Connect Identity Token Creator (Создатель токена идентификации OpenID Connect для сервисного аккаунта).

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

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

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

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

  12. В поле Key type (Тип ключа) выберите JSON.

  13. Нажмите Создать. На компьютер будет скачан JSON-файл с ключом.

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

Вызов 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 для Report State и Notification.
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
  6. Объедините JSON-код Report State и Notification и токен в 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. Получите определение сервиса буферов протокола для Home Graph API.
  2. Следуйте инструкциям в документации для разработчиков gRPC, чтобы создать заглушки клиента для одного из поддерживаемых языков.
  3. Вызовите метод ReportStateAndNotification.

Node.js

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

  1. Инициализируйте сервис google.homegraph, используя Application Default Credentials.
  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
          }
        }
      }
    }
  }
});
    

Java

Клиентская библиотека HomeGraph API для Java предоставляет привязки для Home Graph API.

  1. Инициализируйте HomeGraphApiService с помощью Application Default Credentials.
  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).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"
}

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

Название поля Определение
detailedAccuracyResult Сводка диагностики, объясняющая конкретное расхождение между полезной нагрузкой Report State и ответом на намерение QUERY.
queriedTime Точная временная метка, когда Google получил ответ QUERY от поставщика услуг.
reportedTime Точная временная метка, когда Google получил уведомление Report State.
agentId Уникальный идентификатор проекта (обычно это идентификатор проекта в Google Home Developer Console).
requestId Уникальный идентификатор корреляции, связанный с определенным ответом на намерение QUERY.
queryReportStateDifferences Объект или список, в котором выделены атрибуты состояния устройства, отличающиеся в ответе QUERY и данных Report State.

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

При вызове 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, но этого ещё не произошло, используйте SYNC, чтобы синхронизировать устройство с Google. Если устройство нужно отключить от Google, прекратите передавать данные о его состоянии, но продолжайте передавать данные о состоянии других устройств, связанных с этим agentUserId.

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

Если устройство находится в офлайн-режиме, вы должны сообщить <code{"online": code="" dir="ltr" false}<="" translate="no"> в Report State в течение пяти минут после изменения поведения устройства. И наоборот, когда устройство снова подключается к интернету, вы должны сообщить <code{"online": code="" dir="ltr" translate="no" true}<=""> в Report State в течение пяти минут после изменения поведения устройства. Когда устройство снова подключается к интернету, партнер должен сообщить обо всех текущих состояниях устройства с помощью reportStateAndNotification API. В этом примере показано, что устройство типа light находится в сети, и сообщается о всех текущих состояниях устройства.
"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }
</code{"online":></code{"online":>