Report State

Report State は、 Google Home アクションが ユーザーのデバイスの最新ステータスを Google Home Graph にプロアクティブに報告する重要な機能です。 QUERY インテントを待つ必要はありません。

Report State は、関連付けられた指定の agentUserId（元の SYNC リクエストで送信）を使用して、ユーザー デバイス のステータスを Google に報告します。Google Assistant は、デバイスの現在のステータスを把握する必要があるアクションを実行する場合、EXECUTE インテントを発行する前にさまざまなサードパーティ クラウドに QUERY インテントを発行する代わりに、Home Graph でステータス情報を調べるだけで済みます。

Report State がない場合、リビングルームに複数のプロバイダの照明がある場合、「OK Google、リビングルームを明るくして」というコマンドでは、以前に報告された内容に基づいて現在の明るさの値を調べるのではなく、複数のクラウドに送信された複数の QUERY インテントを解決する必要があります。最高のユーザー エクスペリエンスを実現するために、 Assistantはデバイスとの間の往復なく、デバイスの現在のステータスを把握する必要があります。

デバイスの最初の SYNC に続いて、プラットフォームはデバイスのステータスを収集して Home Graph に入力する QUERY インテントを送信します。その後、Home Graph には Report State で送信されたステータスのみが保存されます。

Report State を呼び出すときは、特定のトレイトの完全な ステータス データを提供してください。Home Graph ではトレイトごとにステータスが更新され、 Report State が呼び出されるたびにそのトレイトのデータがすべて上書きされます。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 プロジェクト ID が一致するプロジェクトを選択します。
3. [有効にする] をクリックします。

サービス アカウント キーを作成する

Google Cloud Console からサービス アカウント キーを生成する手順は次のとおりです。

1. Google Cloud Console[**サービス アカウント**] ページに移動します。

   [サービス アカウント] ページに移動します。

   [サービス アカウント] ページに進むには、プロジェクトの選択が必要になることがあります。

2. add[**サービス アカウントを作成**] をクリックします。

3. [サービス アカウント名] フィールドに名前を入力します。

4. [サービス アカウント ID] フィールドに ID を入力します。

5. [サービス アカウントの説明] フィールドに説明を入力します。

6. [作成して続行] をクリックします。

7. [**ロール**] プルダウンから、[**サービス アカウント**] > [サービス アカウントの OpenID Connect ID トークン作成者] を選択します。

8. [続行] をクリックします。

9. [完了] をクリックします。

10. サービス アカウントのリストから、作成した上記のサービス アカウントを選択し、 [鍵を管理] を more_vert [操作] メニューから選択します。

11. [鍵を追加] > [新しい鍵を作成] を選択します。

12. [**キーのタイプ**] として [**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();
}
    

Report State をテストする

Cloud-to-cloud 統合の 認定に向けての準備として、Report State をテストすることが重要です。

このテストには、Home Graph Viewer ツールの使用をおすすめします。 このツールは、ダウンロードやデプロイを必要としないスタンドアロンのウェブアプリです。

Report State ダッシュボードも利用できますが、 非推奨で、サポートが終了しています。

Report State ダッシュボード

前提条件

Cloud-to-cloud 統合をテストするには、 サービス アカウント キーと agentUserId が必要です。サービス アカウント キーと agentUserId がすでにある場合は、Deploy the Report State Dashboard をご覧ください。

Report State ダッシュボードをデプロイする

プロジェクトのサービス アカウント キーとエージェント ユーザー ID を取得したら、 最新バージョンを Report State ダッシュボードからダウンロードしてデプロイします。 最新バージョンをダウンロードしたら、付属の README.MD ファイルの手順に沿って操作します。

Report State ダッシュボードをデプロイしたら、次の URL からダッシュボードにアクセスします（your_project_id を自分のプロジェクト ID に置き換えます）。

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

ダッシュボードで、以下の手順を行います。

• アカウントキー ファイルを選択する
• agentUserId を追加する

次に、[List]（リスト）をクリックします。

すべてのデバイスが一覧表示されます。一覧が表示されると、[Refresh]（更新）ボタンを使用してデバイスのステータスを更新できます。デバイスのステータスが変化した場合、その行は緑色でハイライト表示されます。

Report State の不一致

クエリベースの Report State の精度は、ユーザーがクエリを実行したときに、デバイスの最新の Report State がデバイスのステータスとどの程度一致しているかを測定します。この値は 99.5% になることが想定されています。プロジェクトの Report State の精度 の現在のステータスの詳細については、 デバイスのヘルス - ステータスの精度をご覧ください。ログ エクスプローラからReport State の不一致ログ の詳細を確認することもできます。

Report State の不一致ログの例を次に示します。

{
  "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 の不一致ログのフィールド定義

エラー レスポンス

Report State を呼び出したとき、次のいずれかのエラー レスポンスが返される場合があります。レスポンスは、HTTP ステータス コードの形で受け取ります。

• 400 Bad Request - サーバーがクライアントから送信されたリクエストを 不正な構文のため処理できませんでした。一般的な原因としては、不正な形式の JSON や、文字列値に "" でなく null を使っていることなどが挙げられます。
• 404 Not Found - リクエストされたリソースは見つかりませんでしたが、将来使用可能になる可能性があります。通常、これはリクエストされたデバイスが見つからないことを意味します。また、ユーザー アカウントが Google にリンクされていないか、無効な agentUserId を受け取ったことを意味する場合もあります。SYNCagentUserId

オンラインとオフラインのステータス報告

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