Google Home Developer Center へようこそ。スマートホームアクションの開発方法を学習できます。注: アクションの構築は、引き続き Actions Console で行います。

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

Report State

Report State は、 Home アクションは、検出ルールの最新の状態をプロアクティブに報告します。ユーザーのデバイスが Google Home Graph に復帰するまでの時間を QUERY インテント。

Report State は、ユーザーデバイスの状態を Google に報告します。指定された agentUserId が関連付けられている（元の SYNC リクエストなど）。Google Assistant さんが操作をリクエストしたときデバイスの現在の状態を理解する必要があるため、代わりに Home Graph の状態情報を使用する QUERY インテントを発行する前に、さまざまなサードパーティクラウドに EXECUTE インテント。

Report State を使用せずに、複数のプロバイダの照明が「OK Google, リビングルームを明るくして」というコマンドを使用するには、複数のクラウドに送信された複数の QUERY インテントを解決する検出された現在の輝度値に基づいて現在の明るさの値をあります。最高のユーザーエクスペリエンスのために Assistant にはデバイスの現在の状態が必要です。デバイスへのラウンドトリップは不要です

デバイスに対する最初の SYNC の後で、プラットフォームは QUERY インテントを送信します。このメソッドは、Home Graph にデータを入力するデバイスの状態を収集します。その時点以降、Home Graph はその時点の状態のみを保存します。 Report State で送信されました。

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 を入力します。
[ロール] リストから、[サービスアカウント] > [サービスアカウントトークン作成者] を選択します。
[キーのタイプ] として [JSON] を選択します。
[作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。

API を呼び出す

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

HTTP

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"

gRPC

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

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

Node.js

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

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。

そのためには、Home Graph ビューアツールダウンロードやデプロイが不要なスタンドアロンのウェブアプリです。

Report State ダッシュボードは引き続き使用できますが、サポートを終了しました

Report State ダッシュボード

前提条件

アクションをテストするには、サービスアカウントキーと agentUserId が必要です。すでにサービスアカウントキーがあり、 agentUserId は、Report State をデプロイするをご覧ください。ダッシュボードをご覧ください。

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

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

注: 以下の手順を行う場合は、正しい GCP プロジェクトこれは、smart home プロジェクト ID と一致するプロジェクトです。

Google Cloud Console で、[サービスアカウントキーの作成] ページに移動します。
[サービスアカウントキーの作成] ページに移動
[サービスアカウント] リストから [新しいサービスアカウント] を選択します。
[サービスアカウント名] フィールドに名前を入力します。
[サービスアカウント ID] フィールドに 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 で設定した値と同じ値を設定します。
で確認できます。 <ph type="x-smartling-placeholder">
</ph>
図 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