Report State

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Report State は、Google Home Action が、QUERY インテントを待つのではなく、ユーザーのデバイスの最新ステータスを Google Home Graph に事前に通知できるようにする重要な機能です。

Report State は、ユーザー デバイスのステータスを、そのデバイスに関連付けられた（元の SYNC リクエストで送信された）特定の agentUserId とともに Google に通知します。これにより、デバイスの現在のステータスがわからなければ実行できないアクションが要求された場合、Google Assistant は Home Graph でステータス情報を調べるだけで済みます。さまざまなサードパーティ クラウドに QUERY インテントを発行してから EXECUTE インテントを発行する必要はありません。

Report State がなければ、たとえばリビングルームにある複数のライトのプロバイダがそれぞれ異なる場合、「OK Google, リビングルームを明るくして」というコマンドを受けると、まず複数のクラウドに複数の QUERY インテントを送信して解決しなければなりませんが、これがあれば、前回の通知内容を基準として現在の明るさの値を調べるだけで済みます。最高のユーザー エクスペリエンスを実現するために、Assistant はデバイスとの間の往復なく、デバイスの現在のステータスを把握する必要があります。

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

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. 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);
}
    

Report State をテストする

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

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

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

Report State ダッシュボード

前提条件

Cloud-to-cloud 統合をテストするには、サービス アカウント キーと 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 インテントが適切に処理されていることを確認してください。