Google Home デベロッパー センターにようこそ。スマートホーム アクションの開発方法を学ぶことができます。注: アクションの作成は、引き続き Actions Console で行います。

Report State

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
全アセットの再ビルドが必要

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 トレイトのステータスを通知している場合、ペイロードには isRunningisPaused の両方の値を含める必要があります。

始める

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

Google HomeGraph API を有効にする

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

    [HomeGraph API] ページに移動
  2. 自分のスマートホーム プロジェクトと ID が一致するプロジェクトを選択します。
  3. [有効にする] をクリックします。

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

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

: 以下の手順を行う場合は、正しい GCP プロジェクト(スマートホーム プロジェクト ID と一致するプロジェクト)を使用していることをご確認ください。
  1. GCP Console で [サービス アカウント キーの作成] ページに移動します。

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

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

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

API を呼び出す

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

HTTP

HomeGraph API は HTTP エンドポイントを提供します。

  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

HomeGraph API は gRPC エンドポイントを提供します。

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

Node.js

Google API Node.js クライアントは、HomeGraph 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 をテストすることが重要です。

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