Report State は、スマートホーム アクションが QUERY
インテントを待つのではなく、ユーザーのデバイスの最新ステータスを Google のホームグラフに事前に通知する重要な機能です。
Report State は、指定した agentUserId
が関連付けられたユーザー デバイスの状態を Google に報告します(元の SYNC
リクエストで送信されます)。Google アシスタントは、EXECUTE
インテントを発行する前に、さまざまなサードパーティ クラウドに QUERY
インテントを発行する代わりに、デバイスの現在の状態を把握する必要があるアクションをホームグラフで参照するだけで対処できます。
Report State がなければ、たとえばリビングルームにある複数のライトのプロバイダがそれぞれ異なる場合、「OK Google, リビングルームを明るくして」というコマンドを受けると、まず複数のクラウドに複数の QUERY
インテントを送信して解決しなければなりません。Report State があれば、前回の通知をもとに現在の輝度値を調べるだけで済みます。最高のユーザー エクスペリエンスを実現するために、Google アシスタントはデバイスまで往復せずにデバイスの現在のステータスを把握する必要があります。
デバイスに関する最初の SYNC
リクエストの後、プラットフォームは QUERY
インテントを送信してホームグラフに入力するデバイスのステータスを収集します。その後は、Report State で送信されたステータスのみがホームグラフに保存されます。
Report State を呼び出すときは、デバイスの特定のトレイトの完全なステータス データを提供してください。ホームグラフではトレイトごとにステータスが更新され、Report State が呼び出されるたびにそのトレイトのデータがすべて上書きされます。たとえば、StartStop トレイトのステータスを通知している場合、ペイロードには isRunning
と isPaused
の両方の値を含める必要があります。
始める
Report State を実装する手順は次のとおりです。
Google HomeGraph API を有効にする
-
Google Cloud Platform Console で、[HomeGraph API] ページに移動します。
[HomeGraph API] ページに移動 - 自分のスマートホーム プロジェクトと ID が一致するプロジェクトを選択します。
- [有効にする] をクリックします。
サービス アカウント キーを作成する
GCP Console からサービス アカウント キーを生成する手順は次のとおりです。
-
GCP Console で [サービス アカウント キーの作成] ページに移動します。
[サービス アカウント キーの作成] ページに移動 - [サービス アカウント] リストから [新しいサービス アカウント] を選択します。
- [サービス アカウント名] フィールドに名前を入力します。
- [サービス アカウント ID] フィールドに ID を入力します。
[ロール] リストから、[サービス アカウント] > [サービス アカウント トークン作成者] を選択します。
[キーのタイプ] として [JSON] を選択します。
- [作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。
API を呼び出す
以下のタブから選択してください。
HTTP
HomeGraph API は HTTP エンドポイントを提供します。
- ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(JWT)を作成します。詳細については、サービス アカウントを使用した認証をご覧ください。
- oauth2l を使用し、
https://www.googleapis.com/auth/homegraph
スコープを指定して OAuth 2.0 アクセス トークンを取得します。 agentUserId
を使用して JSON リクエストを作成します。 次に Report State と Notification の JSON リクエストの例を示します。- Google ホームグラフ エンドポイントに送信する HTTP POST リクエストに、Report State JSON、Notification JSON、アクセス トークンを含めます。次の例では、テストとして
curl
を使用してコマンドラインでリクエストを行う方法を示します。
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
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
HomeGraph API は gRPC エンドポイントを提供します。
- HomeGraph API 用のプロトコル バッファ サービス定義を取得します。
- gRPC デベロッパー向けドキュメントに沿って、サポートされている言語のうちいずれかのクライアント スタブを生成します。
- ReportStateAndNotification メソッドを呼び出します。
Node.js
Google API Node.js クライアントは、HomeGraph API のバインディングを提供します。
- アプリケーションのデフォルト認証情報を使用して、
google.homegraph
サービスを初期化します。 - ReportStateAndNotificationRequest を使用して
reportStateAndNotification
メソッドを呼び出します。ReportStateAndNotificationResponse でPromise
が返されます。
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 用のバインディングを提供します。
- アプリケーションのデフォルト認証情報を使用して、
HomeGraphApiService
を初期化します。 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 をテストすることが重要です。
Prerequisites
アクションをテストするには、サービス アカウント キーと agentUserId
が必要です。すでにサービス アカウント キーと agentUserId
がある場合は、Report State ダッシュボードのデプロイをご覧ください。
Report State ダッシュボードをデプロイする
プロジェクトのサービス アカウント キーと agentUserId を取得したら、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 インテントを適切に処理していることを確認します。