スマートホームアクションの開発方法を学ぶための新しいデベロッパーセンター、Google Home Developer Center へようこそ。

このページは Cloud Translation API によって翻訳されました。

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

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 を有効にする

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

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

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

注: 以下の手順を行う場合は、正しい GCP プロジェクト（smart home プロジェクト ID と一致するプロジェクト）を使用していることをご確認ください。

Google Cloud Consoleで [サービスアカウント] ページに移動します。
[サービスアカウント] ページに移動します。
[サービスアカウント] ページに進むには、プロジェクトの選択が必要になることがあります。
[ サービスアカウントを作成] をクリックします。
[サービスアカウント名] フィールドに名前を入力します。
[サービスアカウント ID] フィールドに ID を入力します。
[サービスアカウントの説明] フィールドに説明を入力します。
[作成して続行] をクリックします。
[ロール] プルダウンから、[サービスアカウント] > [サービスアカウントの OpenID Connect ID トークン作成者] を選択します。
[続行] をクリックします。
[完了] をクリックします。
サービスアカウントのリストから、作成した上記のサービスアカウントを選択し、の [操作] メニューから [鍵を管理] を選択します。
[鍵を追加] > [新しい鍵を作成] を選択します。
[キーのタイプ] として [JSON] を選択します。
[作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。

サービスアカウントキーの詳しい作成手順と情報については、Google Cloud コンソールのヘルプサイトのサービスアカウントキーの作成と削除をご覧ください。

API を呼び出す

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

HTTPgRPCNode.jsJava

Home Graph が HTTP エンドポイントを提供します。

ダウンロードしたサービスアカウントの JSON ファイルを使用して、JSON ウェブトークン（JWT）を作成します。詳細については、サービスアカウントを使用した認証をご覧ください。
oauth2l を使用し、https://www.googleapis.com/auth/homegraph スコープを指定して OAuth 2.0 アクセストークンを取得します。

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

agentUserId を使用して JSON リクエストを作成します。次に Report State と Notification の JSON リクエストの例を示します。

{
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}

Google ホームグラフエンドポイントに送信する HTTP POST リクエストに、Report State JSON、Notification JSON、アクセストークンを含めます。次の例では、テストとして curl を使用してコマンドラインでリクエストを行う方法を示します。

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

Home Graph が gRPC エンドポイントを提供します。

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

Google API Node.js クライアントは、Home Graph 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 用 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 をテストする

ホームグラフビューア

このタスクにおすすめのツール

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

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

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

Report State ダッシュボード

前提条件

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

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

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

注: 以下の手順を行う場合は、正しい GCP プロジェクト（smart home プロジェクト ID と一致するプロジェクト）を使用していることをご確認ください。

Google Cloud Consoleで [サービスアカウント] ページに移動します。
[サービスアカウント] ページに移動します。
[サービスアカウント] ページに進むには、プロジェクトの選択が必要になることがあります。
[ サービスアカウントを作成] をクリックします。
[サービスアカウント名] フィールドに名前を入力します。
[サービスアカウント ID] フィールドに ID を入力します。
[サービスアカウントの説明] フィールドに説明を入力します。
[作成して続行] をクリックします。
[ロール] プルダウンから、[サービスアカウント] > [サービスアカウントの OpenID Connect ID トークン作成者] を選択します。
[続行] をクリックします。
[完了] をクリックします。
サービスアカウントのリストから、作成した上記のサービスアカウントを選択し、の [操作] メニューから [鍵を管理] を選択します。
[鍵を追加] > [新しい鍵を作成] を選択します。
[キーのタイプ] として [JSON] を選択します。
[作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。

agentUserId を取得する方法

agentUserId を取得する手順は次のとおりです。

OAuth Playground ツールを開きます。
右上隅にある歯車アイコンをクリックして [OAuth 2.0 configuration]（OAuth 2.0 の設定）ダイアログを開きます。
[OAuth endpoints]（OAuth エンドポイント）で、[Custom]（カスタム）を選択します。
スマートホームプロジェクトを作成する際に Actions Console で設定した値を使用して、次のアカウントリンクパラメータを指定します。[Close]（閉じる）をクリックして変更を保存します。
- Authorization endpoint（認証エンドポイント）: このパラメータには、Console で設定した認証 URL の値を設定します。
- Token endpoint（トークンエンドポイント）: このパラメータには、Console で設定したトークン URL の値を設定します。
- OAuth Client ID（OAuth クライアント ID）: このパラメータには、Console で設定した値と同じ値を設定します。
- OAuth Client secret（OAuth クライアントシークレット）: このパラメータには、Console で設定した値と同じ値を設定します。
図 1: OAuth 2.0 を設定する。
[Step 1 - Select & authorize APIs]（ステップ 1 - API を選択して認証する）を展開します。[Input your own scopes]（独自のスコープを入力）に「devices」と入力し、[Authorize APIs]（API を認証）をクリックします。
注: Console で他のスコープも指定した場合は、[Step 1] でそれらのスコープも指定します。
上記の手順が正常に完了すると、OAuth エンドポイントにリダイレクトされます。テスト対象のユーザーアカウントを使用してログインします。ログインが成功すると OAuth Playground にリダイレクトされます（[Step 2]（ステップ 2）が展開され、自動的に生成された認証コードが入力されています）。
[Exchange authorized code for tokens]（認証コードをトークンと交換）をクリックして更新トークンとアクセストークンを取得します。
[Step 3 - Configure request to API]（ステップ 3 - API へのリクエストを設定する）で、次の手順を行います。
1. [HTTP Method]（HTTP メソッド）を [POST] に設定します。
2. [Request URI]（リクエスト URI）をフルフィルメント URL に設定します。
3. [Enter request body]（リクエスト本文を入力）をクリックし、次のサンプル入力を追加します。
```
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.SYNC"
  }]
}
        
```
4. [Send the request]（リクエストを送信）をクリックします。
レスポンスで「agentUserId」フィールドの値を確認します。

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 インテントが適切に処理されていることを確認してください。

Request sync

Send notifications