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

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

ローカルホームのデバッグ

1. 始める前に

スマートホームの統合により、ユーザーの家にある接続済みデバイスを Google アシスタントを通じて制御できるようになります。スマートホームアクションを作成するには、スマートホームインテントを処理できる Cloud Webhook エンドポイントを用意する必要があります。たとえば、ユーザーが「OK Google, 電気をつけて」と言うと、アシスタントはクラウドフルフィルメントにコマンドを送信してデバイスの状態を更新します。

一方、Local Home SDK を使用すると、スマートホームインテントを Google Home デバイスに直接ルーティングするローカルパスを追加できます。これによりスマートホームの統合を強化でき、ユーザーコマンドの処理の信頼性を向上させレイテンシを短縮できます。また、デバイスを識別するローカルフルフィルメントアプリを TypeScript や JavaScript で記述してデプロイし、Google Home スマートスピーカーや Google Nest スマートディスプレイでコマンドを実行することもできます。ユーザーコマンドの実行に既存の標準プロトコルを使用することで、アプリがローカルエリアネットワーク経由で既存のスマートデバイスと直接通信することが可能になります。

スマートホームアクションのデバッグは、本番環境品質のアクションを構築するための重要なステップですが、情報が豊富で使いやすいトラブルシューティングツールやテストツールなしでは困難で時間がかかります。スマートホームアクションのデバッグを容易にするために、Google Cloud Platform（GCP）の指標、ロギング、スマートホーム用テストスイートを利用できます。これらは、アクションの問題を特定して解決するのに役立ちます。

前提条件

スマートホームアクションの作成に関するデベロッパーガイド
スマートホームアクションのローカルフルフィルメントを有効にする Codelab を実行します。

作成するアプリの概要

この Codelab では、スマートホームアクションのローカルフルフィルメントを作成してアシスタントに接続し、スマートホーム向けのテストスイートを使用してローカルホームアプリをデバッグします。Google Cloud Platform（GCP）の指標とロギング。

学習内容

GCP の指標とロギングを使用して本番環境の問題を特定し、解決する方法。
テストスイートを使用して機能や API の問題を特定する方法
ローカル Google Home アプリの開発時に Chrome Dev Tools を使用する方法

必要なもの

Google Chrome の最新版
Google Home アプリがインストールされている iOS または Android デバイス
Google Home スマートスピーカーまたは Google Nest スマートディスプレイ
Node.js バージョン 10.16 以降
Google アカウント
Google Cloud 請求先アカウント

2. 洗濯機アプリを実行する

ソースコードを取得する

下のリンクをクリックして、この Codelab のサンプルを開発マシンにダウンロードします。

または、コマンドラインから GitHub リポジトリのクローンを作成することもできます。

$ git clone https://github.com/google-home/smarthome-debug-local.git

プロジェクトについて

スターターアプリには、スマートホームアクションのローカルフルフィルメントを有効にする Codelab と同様のサブディレクトリと Cloud Functions の関数が含まれています。ここでは、app-start の代わりに app-faulty を使用しています。ローカルの Google Home アプリから始めましょう。動作はするものの、あまりうまくいきません。

Firebase に接続する

ここでは、スマートホームアクションのローカルフルフィルメントを有効にする Codelab で作成したものと同じプロジェクトを使用しますが、この Codelab でダウンロードしたファイルをデプロイします。

app-faulty ディレクトリに移動し、スマートホームアクションのローカルフルフィルメントを有効にする Codelab で作成した Actions プロジェクトを使用して Firebase CLI を設定します。

$ cd app-faulty
$ firebase use <project-id>

Firebase にデプロイする

app-faulty/functions フォルダに移動し、npm を使用して必要な依存関係をすべてインストールします。

$ cd functions
$ npm install

注: 次のメッセージが表示された場合は、無視して続行してください。この警告は一部の古い依存関係が原因で表示されます。詳しくは、こちらをご覧ください。

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

TypeScript コンパイラをダウンロードしてアプリをコンパイルするため、app-faulty/local/ ディレクトリに移動して次のコマンドを実行します。

$ cd ../local
$ npm install
$ npm run build

これにより、index.ts（TypeScript）のソースがコンパイルされ、以下のファイルが app-faulty/public/local-home/ ディレクトリに格納されます。

bundle.js - ローカルアプリと依存関係を含むコンパイル済み JavaScript の出力。
index.html - デバイスでのテストでアプリの配信に使用するローカルホスティングページ。

これで依存関係のインストールとプロジェクトの設定が完了し、アプリを実行する準備が整いました。

$ firebase deploy

コンソールに次のような出力が表示されます。

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<projectcd -id>.web.app

このコマンドは、ウェブアプリと複数の Cloud Functions for Firebase をデプロイします。

HomeGraph を更新する

ブラウザ（https://<project-id>.web.app）で [Hosting URL] を開き、ウェブアプリを表示します。ウェブ UI で [Refresh ] ボタンをクリックし、Request Sync を介して HomeGraph を、故障した洗濯機アプリの最新のデバイスメタデータで更新します。

Google Home アプリを開き、「洗濯機の故障」という新しい名前の洗濯機が表示されることを確認します。デバイスは、Google Nest デバイスがある部屋に割り当ててください。

3. スマート洗濯機を起動する

スマートホームアクションのローカルフルフィルメントを有効にする Codelab をすでに実行している場合は、仮想スマート洗濯機がすでに起動しているはずです。停止した場合は、仮想デバイスを再起動してください。

デバイスを起動する

virtual-device/ ディレクトリに移動し、引数として設定パラメータを渡してデバイススクリプトを実行します。

$ cd ../../virtual-device
$ npm install
$ npm start -- \
  --deviceId=deviceid123 --projectId=<project-id> \
  --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK

デバイススクリプトが、想定どおりのパラメータで実行されたことを確認します。

(...): UDP Server listening on 3311
(...): Device listening on port 3388
(...): Report State successful

4. Local Home アプリをテストする

Google Home デバイスに音声コマンドを送信すると、以下のようなことが可能になります。

「OK Google, 洗濯機をつけて」

「OK Google, 強制的にローカルに」

「OK Google, 洗濯機を止めて」

Google アシスタントが「現在、不具合のある洗濯機を利用できないようです」という応答を返します。「強制ローカル」の後に洗濯機を制御しようとしたとき。

これは、ローカルパス経由でデバイスに到達できないことを意味します。「OK Google, ローカルに強制ローカル」と話しかける前に動作していたというのも、ローカルパス経由でデバイスにアクセスできない場合、クラウドパスを使用するようフォールバックするためです。ただし、「強制ローカル」の後はクラウドパスにフォールバックするオプションは無効になります。

何が問題なのかを見つけるために、Google Cloud Platform（GCP）の指標、ロギング、Chrome デベロッパーツールという Google のツールを活用してみましょう。

5. Local Home アプリをデバッグする

次のセクションでは、Google が提供するツールを使用して、ローカルパス経由でデバイスにアクセスできない理由を調べます。Google Chrome デベロッパーツールを使用すると、Google Home デバイスへの接続、コンソールログの表示、ローカル Home アプリのデバッグを行うことができます。また、カスタムログを Cloud Logging に送信して、ローカルホームアプリでユーザーがよく目にするエラーを把握することもできます。

Chrome デベロッパーツールを接続する

次の手順に沿って、デバッガをローカルフルフィルメントアプリに接続します。

Google Home デバイスが、Actions Console プロジェクトへのアクセス権限を持つユーザーにリンクされていることを確認します。
Google Home デバイスを再起動します。これにより、Actions Console で設定した HTML の URL とスキャン設定が取得されます。
開発マシンで Chrome を起動します。
新しい Chrome タブを開き、アドレスフィールドに「chrome://inspect」と入力して、インスペクタを起動します。

ページ上にデバイスのリストが表示され、Google Home デバイスの名前の下にアプリの URL が表示されます。

インスペクタを起動する

アプリの URL の下にある [Inspect]（検査）をクリックして Chrome デベロッパーツールを起動します。[Console]（コンソール）タブを選択し、TypeScript アプリによって出力された IDENTIFY インテントの内容が表示されることを確認します。

この出力は、IDENTIFY ハンドラが正常にトリガーされたものの、IdentifyResponse で返された verificationId が HomeGraph 内のどのデバイスとも一致しないことを意味します。カスタムログをいくつか追加して、理由を確認してみましょう。

カスタムログを追加する

Local Home SDK によって DEVICE_VERIFICATION_FAILED エラーが出力されますが、根本原因の特定にはあまり役立ちません。カスタムログをいくつか追加して、スキャンデータが正しく読み取られて処理されていることを確認してみましょう。エラーで Promise が拒否されると、エラーメッセージが実際に Cloud Logging にも送信されることに注意してください。

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  // Is there something wrong here?
  const localDeviceId = Buffer.from(scanData.data);
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  // Add custom logs
  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_device', 'Invalid device id from scan data ' +
        localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

また、ローカルの Google Home アプリのバージョンを変更し、正しいバージョンを使用しているか特定できるようにします。

local/index.ts

const localHomeSdk = new App('1.0.1');

カスタムログを追加したら、アプリを再度コンパイルして Firebase に再デプロイする必要があります。

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

次に、Google Home デバイスを再起動して、更新されたローカルの Google Home アプリを読み込めるようにします。Google Home デバイスが想定したバージョンを使用しているかどうかは、Chrome デベロッパーツールのコンソールログで確認できます。

Cloud Logging にアクセスする

Cloud Logging を使用してエラーを見つける方法を見ていきましょう。プロジェクトの Cloud Logging にアクセスする手順は次のとおりです。

Cloud Platform コンソールでプロジェクト ページに移動します。
スマートホームプロジェクトを選択します。
[オペレーション] で、[ロギング] > [ログエクスプローラ] を選択します。

ロギングデータへのアクセスは、Actions プロジェクトのユーザーの Identity and Access Management（IAM）で管理します。ロギングデータのロールと権限の詳細については、Cloud Logging のアクセス制御をご覧ください。

高度なフィルタを使用する

ローカルデバイスが識別できないためローカルパスが機能していないため、IDENTIFY インテントでエラーが発生しています。しかし、問題を正確に把握したいので、まず IDENTIFY ハンドラで発生するエラーを除外します。

[クエリを表示] トグルをクリックすると、[クエリビルダー] ボックスに変わります。[クエリビルダー] ボックスに「jsonPayload.intent="IDENTIFY"」と入力し、[クエリを実行] ボタンをクリックします。

その結果、IDENTIFY ハンドラでスローされるすべてのエラーログが取得されます。次に、最後のエラーを開きます。IDENTIFY ハンドラで Promise を拒否する際に設定した errorCode と debugString があります。

debugString から、ローカルデバイス ID が想定された形式ではないことがわかります。Local Home アプリは、deviceid で始まり 3 桁の数字が続く文字列としてローカルデバイス ID を取得することを想定していますが、ここでのローカルデバイス ID は 16 進数の文字列です。

エラーを修正してください

スキャンデータからローカルデバイス ID を解析するソースコードに戻ると、文字列をバイトに変換する際にエンコードを指定していないことがわかります。スキャンデータは 16 進文字列として受信されるため、Buffer.from() を呼び出すときは文字エンコードとして hex を渡します。

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  const localDeviceId = Buffer.from(scanData.data, 'hex');
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
      'invalid_device', 'Invalid device id from scan data ' +
      localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

また、ローカルの Google Home アプリのバージョンを変更し、正しいバージョンを使用しているか特定できるようにします。

local/index.ts

const localHomeSdk = new App('1.0.2');

エラーを修正したら、アプリをコンパイルして Firebase に再デプロイします。app-faulty/local で、以下を実行します。

$ npm run build
$ firebase deploy --only hosting

修正をテストする

デプロイが完了したら、Google Home デバイスを再起動して、更新されたローカルの Google Home アプリを読み込めるようにします。ローカルの Google Home アプリのバージョンが 1.0.2 であることを確認し、今度は Chrome デベロッパーツールコンソールにエラーが表示されないはずです。

もう一度デバイスにコマンドを送信してみてください。

「OK Google, 強制的にローカルに設定」

「OK Google, 洗濯機を止めて」

「OK Google, 洗濯機をつけて」

...

「OK Google, デフォルトに設定」

6. スマートホーム用のテストスイートを実行する

Google Home アプリのタップ操作または音声コマンドを使用してデバイスを検証したら、自動化されたスマートホーム用テストスイートを使用して、アクションに関連付けられたデバイスのタイプとトレイトに基づいてユースケースを検証できます。テストスイートでは、アクションの問題を検出するための一連のテストが実行され、イベントログを確認する前にデバッグを迅速に行うため、失敗したテストケースに関する情報メッセージが表示されます。

スマートホーム向けのテストスイートを実行する

テストスイートによるスマートホームアクションをテストする手順は次のとおりです。

ウェブブラウザで [Test Suite for smart home] を開きます。
右上のボタンを使用して Google にログインします。これにより、テストスイートはコマンドを Google アシスタントに直接送信できます。
[Project ID]（プロジェクト ID）フィールドに、スマートホームアクションのプロジェクト ID を入力します。[次へ] をクリックして次に進みます。
[Test Settings] ステップの [Devices and Trais] セクションに、故障した洗濯機が表示されます。
サンプルの洗濯機アプリには、洗濯機の追加、削除、名前変更を行う UI がないため、[Test Request Sync] オプションを無効にします。本番環境システムでは、ユーザーがデバイスの追加、削除、名前変更を行うたびに、Request Sync をトリガーする必要があります。
ローカルパスとクラウドパスの両方をテストするため、[Local Home SDK] オプションは有効のままにします。
[Next: Test environment] をクリックしてテストを開始します。

テストが完了すると、ローカルパスの一時停止/再開テストは失敗しますが、クラウドパスの一時停止/再開テストは合格します。

エラーメッセージを分析

失敗したテストケースのエラーメッセージを詳しく確認します。テストで想定される状態と、実際の状態を知ることができます。このケースでは、「Pause the Washer」と想定されている状態は isPaused: true ですが、実際の状態では isPaused: false になっています。同様に、「洗濯機を一時停止」の場合、想定される状態は isPaused: true ですが、実際の状態では isPaused: false になっています。

エラーメッセージを見ると、ローカルパスでは isPaused の状態を逆に設定しています。

エラーを特定して修正する

ローカルホームアプリがデバイスに実行コマンドを送信するソースコードを探します。getDataCommand() は、デバイスに送信される実行コマンドで payload を設定するために executeHandler() によって呼び出される関数です。

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                // Is there something wrong here?
                isPaused: params.pause ? false : true
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

実際には、isPause を逆の状態に設定しています。params.pause が true の場合は true に設定し、それ以外の場合は false に設定する必要があります。これを修正しましょう。

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                isPaused: params.pause ? true : false
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

ローカルの Google Home アプリのバージョンを変更して、正しいバージョンを使用しているかどうかを特定できるようにします。

local/index.ts

const localHomeSdk = new App('1.0.3');

アプリを再度コンパイルして Firebase に再デプロイすることを忘れないでください。app-faulty/local で、以下を実行します。

$ npm run build
$ firebase deploy --only hosting

次に、Google Home デバイスを再起動して、更新されたローカルの Google Home アプリを読み込めるようにします。ローカルの Google Home アプリのバージョンが 1.0.3 であることを確認します。

修正をテストする

ここで、同じ設定でスマートホーム用のテストスイートを再実行すると、すべてのテストケースに合格していることがわかります。

7. 完了

これで、スマートホームとアプリのテストスイートを使用して、Local Home アプリのトラブルシューティングを行う方法を学びました。Cloud Logging です。

詳細

他にも以下のことを試してみてください。

サポートされているトレイトをデバイスに追加し、テストスイートでテストします。
各インテントハンドラにカスタムログを追加し、Cloud Logging で表示する。
アクションに関する有用な使用状況の指標を取得するために、ダッシュボードを作成してアラートを設定し、プログラムで指標データにアクセスする。

また、アクションをユーザーに公開するための認定プロセスなど、アクションのテストと送信の詳細もご確認ください。

ローカルホームのデバッグ

1. 始める前に

前提条件

作成するアプリの概要

学習内容

必要なもの

2. 洗濯機アプリを実行する

ソースコードを取得する

プロジェクトについて

Firebase に接続する

Firebase にデプロイする

HomeGraph を更新する

3. スマート洗濯機を起動する

デバイスを起動する

4. Local Home アプリをテストする

5. Local Home アプリをデバッグする

Chrome デベロッパー ツールを接続する

インスペクタを起動する

カスタムログを追加する

Cloud Logging にアクセスする

高度なフィルタを使用する

エラーを修正してください

修正をテストする

6. スマートホーム用のテストスイートを実行する

スマートホーム向けのテストスイートを実行する

エラー メッセージを分析

エラーを特定して修正する

修正をテストする

7. 完了

詳細

Chrome デベロッパーツールを接続する

エラーメッセージを分析