Report State

Report State は、Home アクションが QUERY インテントを待つのではなく、ユーザーのデバイスの最新ステータスを Google Home Graph に事前にレポートするための重要な機能です。

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

Report State がない場合、リビングルームにある複数のプロバイダから提供される照明に対して「OK Google, リビングルームを明るくして」コマンドを使用するには、以前に報告された値に基づいて現在の明るさの値を調べるのではなく、複数のクラウドに送信される複数の QUERY インテントを解決する必要があります。最適なユーザー エクスペリエンスを実現するには、Assistant がデバイスとの往復を必要とせずに、デバイスの現在の状態を保持する必要があります。

デバイスの最初の SYNC に続いて、プラットフォームは QUERY インテントを送信し、デバイスの状態を収集して Home Graph に値を設定します。それ以降、Home GraphReport State で送信された状態のみを保存します。

Report State を呼び出すときは、特定のトレイトの完全な状態データを提供してください。Home Graph は、トレイトごとに状態を更新し、Report State 呼び出しが行われると、そのトレイトのすべてのデータを上書きします。たとえば、StartStop トレイトの状態を報告する場合、ペイロードには isRunningisPaused の両方の値を含める必要があります。

使ってみる

Report State を実装する手順は次のとおりです。

Google HomeGraph API を有効にする

  1. Google Cloud Console で、[HomeGraph API] ページに移動します。

    [HomeGraph API] ページに移動
  2. smart home プロジェクト ID と一致するプロジェクトを選択します。
  3. [有効にする] をクリックします。

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

Google Cloud Console からサービス アカウント キーを生成するには、次の手順を行います。

: 以下の手順を行う場合は、正しい GCP プロジェクトこれは、smart home プロジェクト ID と一致するプロジェクトです。
  1. Google Cloud Console で [サービス アカウント キーの作成] ページに移動します。

    [サービス アカウント キーの作成] ページに移動
  2. [サービス アカウント] リストから [新しいサービス アカウント] を選択します。
  3. [サービス アカウント名] フィールドに名前を入力します。
  4. [サービス アカウント ID] フィールドに ID を入力します。
  5. [ロール] リストから、[サービス アカウント] > [サービス アカウント トークン作成者] を選択します。

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

  7. [作成] をクリックします。キーが含まれている JSON ファイルがパソコンにダウンロードされます。

API を呼び出す

以下のタブから選択してください。

HTTP

Home GraphHTTP エンドポイントを提供します。

  1. ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(JWT)を作成します。詳細については、サービス アカウントを使用した認証をご覧ください。
  2. oauth2l を使用し、https://www.googleapis.com/auth/homegraph スコープを指定して OAuth 2.0 アクセス トークンを取得します。
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId を使用して JSON リクエストを作成します。 次に Report State と Notification の JSON リクエストの例を示します。
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Google ホームグラフ エンドポイントに送信する HTTP POST リクエストに、Report State JSON、Notification JSON、アクセス トークンを含めます。次の例では、テストとして 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 GraphgRPC エンドポイントを提供します。

  1. HomeGraph API 用のプロトコル バッファ サービス定義を取得します。
  2. gRPC デベロッパー向けドキュメントに沿って、サポートされている言語のうちいずれかのクライアント スタブを生成します。
  3. ReportStateAndNotification メソッドを呼び出します。

Node.js

Google API Node.js クライアントは、Home Graph API 用のバインディングを提供します。

  1. アプリケーションのデフォルト認証情報を使用して、google.homegraph サービスを初期化します。
  2. ReportStateAndNotificationRequest を使用して reportStateAndNotification メソッドを呼び出します。ReportStateAndNotificationResponsePromise が返されます。
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

Java 用 HomeGraph API クライアント ライブラリは、HomeGraph API 用のバインディングを提供します。

  1. アプリケーションのデフォルト認証情報を使用して HomeGraphApiService を初期化します。
  2. ReportStateAndNotificationRequest を使用して reportStateAndNotification メソッドを呼び出します。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);
}
    

Report State をテストする

このタスクに推奨されるツール

アクションの認定を受けるための準備として、Report State をテストすることが重要です。

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

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 を受け取った可能性もあります。agentUserIdSYNC レスポンスで提供された値と一致していること、DISCONNECT インテントが適切に処理されていることを確認してください。