Report State

Report State は、QUERY インテントを待つのではなく、Home アクションがユーザーのデバイスの最新ステータスを Google Home Graph に前もって報告できるようにする重要な機能です。

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

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 を有効にする
• サービス アカウント キーを作成する
• 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. [サービス アカウント] リストから [新しいサービス アカウント] を選択します。
3. [サービス アカウント名] フィールドに名前を入力します。
4. [サービス アカウント ID] フィールドに ID を入力します。

5. [ロール] リストから、[サービス アカウント] > [サービス アカウント トークン作成者] を選択します。

6. [キーのタイプ] として [JSON] を選択します。

7. [作成] をクリックするとキーが含まれている 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);
}
    

Report State をテストする

アクションの認定に向けての準備として、Report State のテストが重要です。

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

Report State ダッシュボードは引き続き使用できますが、非推奨であり、サポートは終了しています。

Report State ダッシュボード

前提条件

アクションをテストするには、サービス アカウント キーと agentUserId が必要です。サービス アカウント キーと agentUserId がすでにある場合は、Report State ダッシュボードをデプロイするをご覧ください。

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 を呼び出すと、次のいずれかのエラー レスポンスが返されることがあります。レスポンスは、HTTP ステータス コードの形で受け取ります。

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