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

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

スマートホームデバイスを Google アシスタントにリンクする

1. 始める前に

モノのインターネット（IoT）のデベロッパーは、Google Home アプリのタップ操作やアシスタントの音声コマンドでデバイスを操作できるスマートホームアクションを作成できます。

スマートホームアクションは、ホームグラフを使用して家とそのデバイスに関するコンテキストデータを提供し、家の論理的な地図を作成します。このコンテキストにより、アシスタントはユーザーのリクエストを屋内の位置と関連付けて、より自然な形で理解できるようになります。たとえば、ホームグラフには、「さまざまなメーカーの複数のデバイス（エアコン、照明、扇風機、掃除機など）が置かれたリビングルーム」というコンセプトを保存できます。

前提条件

スマートホームアクションを作成するデベロッパーガイド

作成するアプリの概要

この Codelab では、仮想スマート洗濯機を管理するクラウドサービスを公開し、スマートホームアクションを構築してアシスタントにリンクします。

演習内容

スマートホームクラウドサービスをデプロイする方法
サービスをアシスタントにリンクする方法
デバイスの状態変化を Google に公開する方法

必要なもの

ウェブブラウザ（Google Chrome など）
Google Home アプリがインストールされている iOS デバイスまたは Android デバイス
Node.js バージョン 10.16 以降
Google Cloud の請求先アカウント

2. はじめに

アクティビティ管理を有効にする

Google アシスタントを使用するには、特定のアクティビティデータを Google と共有する必要があります。このデータは Google アシスタントが適切に機能するために必要となります。ただし、データの共有は SDK に固有の要件ではありません。このデータを共有するには、Google アカウントを作成します（まだ作成していない場合）。任意の Google アカウントを使用できます。デベロッパーアカウントである必要はありません。

アシスタントで使用する Google アカウントの [アクティビティ管理] ページを開きます。

以下の切り替えスイッチが有効になっていることを確認します。

[ウェブとアプリのアクティビティ] - これに加えて、[Chrome の履歴と Google サービスを使用するサイト、アプリ、デバイスでのアクティビティを含める] チェックボックスがオンになっていることも確認してください。
[デバイス情報]
[音声アクティビティ]

Actions プロジェクトを作成する

Actions on Google のデベロッパーコンソールに移動します。
[New Project]（新しいプロジェクト）をクリックし、プロジェクトの名前を入力して [CREATE PROJECT]（プロジェクトを作成）をクリックします。

スマートホームアプリを選択する

Actions Console の概要画面で [Smart Home]（スマートホーム）を選択します。

[Smart home] エクスペリエンスカードを選択し、[Start Building] をクリックすると、プロジェクトコンソールが表示されます。

Firebase CLI をインストールする

Firebase コマンドラインインターフェース（CLI）を使用すると、ウェブアプリをローカルで提供し Firebase Hosting にデプロイできます。

CLI をインストールするには、ターミナルから次の npm コマンドを実行します。

npm install -g firebase-tools

CLI が正しくインストールされたことを確認するには、次のコマンドを実行します。

firebase --version

次のコマンドを実行して、Google アカウントで Firebase CLI を承認します。

firebase login

3.スターターアプリを実行する

開発環境の設定が完了したので、スタータープロジェクトをデプロイし、すべてが正しく設定されていることを確認しましょう。

ソースコードを取得する

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

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

git clone https://github.com/google-home/smarthome-washer.git

プロジェクトについて

スタータープロジェクトには、以下のサブディレクトリが含まれています。

public: スマート洗濯機の状態を簡単に制御、モニタリングするためのフロントエンド UI。
functions: Cloud Functions for Firebase と Firebase Realtime Database を使用してスマート洗濯機を管理する、実装が完了したクラウドサービス。

Firebase に接続する

washer-start ディレクトリに移動し、Actions プロジェクトに Firebase CLI を設定します。

cd washer-start
firebase use <project-id>

Firebase プロジェクトを設定する

Firebase プロジェクトを初期化します。

firebase init

CLI 機能、Realtime Database、Functions、Firebase Hosting を含む Hosting 機能を選択します。

? Which Firebase CLI features do you want to set up for this directory? Press Space to select features, then
 Enter to confirm your choices.
❯◉ Realtime Database: Configure a security rules file for Realtime Database and (optionally) provision default instance
 ◯ Firestore: Configure security rules and indexes files for Firestore
 ◉ Functions: Configure a Cloud Functions directory and its files
 ◉ Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys
 ◯ Hosting: Set up GitHub Action deploys
 ◯ Storage: Configure a security rules file for Cloud Storage
 ◯ Emulators: Set up local emulators for Firebase products
 ◯ Remote Config: Configure a template file for Remote Config
 ◯ Extensions: Set up an empty Extensions manifest

これにより、プロジェクトに必要な API と機能が初期化されます。

プロンプトが表示されたら、Realtime Database を初期化します。データベースインスタンスのデフォルトの場所を使用できます。

? It seems like you haven't initialized Realtime Database in your project yet. Do you want to set it up?
Yes

? Please choose the location for your default Realtime Database instance:
us-central1

スタータープロジェクトのコードを使用しているため、セキュリティルールのデフォルトファイルを選択します。既存のデータベースルールファイルを上書きしないよう注意してください。

? File database.rules.json already exists. Do you want to overwrite it with the Realtime Database Security Rules for <project-ID>-default-rtdb from the Firebase Console?
No

プロジェクトを再初期化する場合、コードベースを初期化するか上書きするか尋ねられたら [上書き] を選択します。

? Would you like to initialize a new codebase, or overwrite an existing one?
Overwrite

Functions を構成するときは、デフォルトのファイルを使用する必要があります。プロジェクトサンプルの既存の index.js ファイルと package.json ファイルを上書きしないようにしてください。

? What language would you like to use to write Cloud Functions?
JavaScript

? Do you want to use ESLint to catch probable bugs and enforce style?
No

? File functions/package.json already exists. Overwrite?
No

? File functions/index.js already exists. Overwrite?
No

プロジェクトを再初期化する場合、functions/.gitignore を初期化するか上書きするかを尋ねられたら [No] を選択します。

? File functions/.gitignore already exists. Overwrite?
No

? Do you want to install dependencies with npm now?
Yes

最後に、プロジェクトコードの public ディレクトリと既存の index.html ファイルを使用するように Hosting の設定を構成します。ESLint を使用するように求められたら [No] を選択します。

? What do you want to use as your public directory?
public

? Configure as a single-page app (rewrite all urls to /index.html)?
Yes

? Set up automatic builds and deploys with GitHub?
No

? File public/index.html already exists. Overwrite?
 No

誤って ESLint を有効にしていた場合、無効にするには、次の 2 つの方法があります。

GUI を使用して、プロジェクトの下にある ../functions フォルダに移動し、隠しファイル .eslintrc.js を選択して削除します。同じような名前の .eslintrc.json と取り違えないでください。
コマンドラインを使用する場合:
```
cd functions
rm .eslintrc.js
```

Firebase の構成が完全で正確であることを確認するには、firebase.json ファイルを app-done ディレクトリから app-start ディレクトリにコピーして、app-start にあるファイルを上書きします。

app-start ディレクトリで:

cp -vp ../app-done/firebase.json .

Firebase にデプロイする

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

firebase deploy

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

...

✔ Deploy complete!

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

このコマンドは、いくつかの Cloud Functions for Firebase とともにウェブアプリをデプロイします。

ブラウザで Hosting URL（https://<project-id>.web.app）を開き、ウェブアプリを表示します。次のようなインターフェースが表示されます。

このウェブ UI は、デバイスの状態を表示したり変更したりするためのサードパーティプラットフォームを表したものです。データベースへのデバイス情報の入力を開始するには、[UPDATE]（更新）をクリックします。ページの表示は変化しませんが、洗濯機の現在の状態がデータベースに保存されます。

Actions Console を使用して、デプロイしたクラウドサービスを Google アシスタントに接続します。

Actions Console プロジェクトを構成する

[Overview]（概要）> [Build your Action]（アクションの構築）で、[Add Action(s)]（アクションを追加）を選択します。スマートホームインテントのフルフィルメントを提供する Cloud Functions の URL を入力し、[Save]（保存）をクリックします。

https://us-central1-<project-id>.cloudfunctions.net/smarthome

[Develop] > [Invocation]（呼び出し）タブで、アクションの [Display Name]（表示名）を追加して [Save] をクリックします。この名前は Google Home アプリに表示されます。

アカウントリンクを有効にするには、左側のナビゲーションで [Develop] > [Account linking]（アカウントリンク）を選択します。以下の値でアカウントリンクを設定します。

クライアント ID	`ABC123`
クライアントシークレット	`DEF456`
認証 URL	`https://us-central1-<project-id>.cloudfunctions.net/fakeauth`
トークンの URL	`https://us-central1-<project-id>.cloudfunctions.net/faketoken`

[Save] をクリックしてアカウントリンクの設定を保存し、[Test]（テスト）をクリックしてプロジェクトでのテストを有効にします。

[Simulator]（シミュレータ）にリダイレクトされます。[Test now enabled] が表示されない場合は、[テストをリセット] をクリックして、テストが有効になっていることを確認します。

これで、デバイスの状態とアシスタントをリンクするために必要な Webhook の実装を開始できるようになりました。

4. 洗濯機を作成する

アクションの設定が完了したら、次はデバイスを追加してデータを送信します。クラウドサービスでは、以下のインテントを処理する必要があります。

SYNC インテント。ユーザーがリンク済みのデバイスについてアシスタントが問い合わせたときに発生します。これは、ユーザーがアカウントをリンクしたときにサービスに送信されます。ユーザーのすべてのデバイスとその機能を格納した JSON ペイロードで応答する必要があります。
QUERY インテント。デバイスの現在の状態をアシスタントが問い合わせたときに発生します。リクエストされた各デバイスの状態を格納した JSON ペイロードで応答する必要があります。
EXECUTE インテント。アシスタントがユーザーに代わってデバイスを制御するときに発生します。リクエストされた各デバイスの実行状態を格納した JSON ペイロードで応答する必要があります。
DISCONNECT インテントは、ユーザーがアシスタントからアカウントのリンクを解除したときに発生します。このユーザーのデバイスのイベントをアシスタントに送信するのを停止する必要があります。

以降のセクションでは、すでにデプロイした関数を、これらのインテントを処理できるように更新します。

SYNC レスポンスを更新する

functions/index.js を開きます。このファイルには、アシスタントからのリクエストに応答するコードが含まれています。

デバイスのメタデータと機能を返して SYNC インテントを処理する必要があります。onSync 配列の JSON を更新して、洗濯機のデバイス情報と推奨トレイトを含めます。

index.js

app.onSync((body) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: USER_ID,
      devices: [{
        id: 'washer',
        type: 'action.devices.types.WASHER',
        traits: [
          'action.devices.traits.OnOff',
          'action.devices.traits.StartStop',
          'action.devices.traits.RunCycle',
        ],
        name: {
          defaultNames: ['My Washer'],
          name: 'Washer',
          nicknames: ['Washer'],
        },
        deviceInfo: {
          manufacturer: 'Acme Co',
          model: 'acme-washer',
          hwVersion: '1.0',
          swVersion: '1.0.1',
        },
        willReportState: true,
        attributes: {
          pausable: true,
        },
      }],
    },
  };
});

Firebase にデプロイする

Firebase CLI を使用して、更新したクラウドフルフィルメントをデプロイします。

firebase deploy --only functions

Google アシスタントにリンクする

スマートホームアクションをテストするには、プロジェクトを Google アカウントにリンクする必要があります。これにより、同じアカウントにログインしている Google アシスタント画面と Google Home アプリでテストできるようになります。

スマートフォンで Google アシスタントの設定を開きます。なお、コンソールと同じアカウントでログインする必要があります。
[Google アシスタント] > [設定] > [スマートホーム]（[アシスタント] の下）に移動します。
右上にある検索アイコンをクリックします。
接頭辞 [test] を使用してテストアプリを検索し、特定のテストアプリを見つけます。
そのアイテムを選択します。Google アシスタントがサービスで認証を行い、SYNC リクエストを送信してデバイスのリストをユーザーに提供するようサービスに依頼します。

Google Home アプリを開いて、洗濯機デバイスが表示されることを確認します。

5. コマンドとクエリを処理する

クラウドサービスが洗濯機デバイスを Google に正しく報告できたので、次は、デバイスの状態をリクエストしてコマンドを送信する機能を追加します。

QUERY インテントを処理する

QUERY インテントにはデバイスのセットが含まれます。デバイスごとに現在の状態を返す必要があります。

functions/index.js で、インテントリクエストに含まれる対象デバイスのリストを処理するよう QUERY ハンドラを編集します。

index.js

app.onQuery(async (body) => {
  const {requestId} = body;
  const payload = {
    devices: {},
  };
  const queryPromises = [];
  const intent = body.inputs[0];
  for (const device of intent.payload.devices) {
    const deviceId = device.id;
    queryPromises.push(queryDevice(deviceId)
        .then((data) => {
        // Add response to device payload
          payload.devices[deviceId] = data;
        }
        ));
  }
  // Wait for all promises to resolve
  await Promise.all(queryPromises);
  return {
    requestId: requestId,
    payload: payload,
  };
});

リクエストに含まれるデバイスごとに、Realtime Database に保存されている現在の状態を返します。洗濯機の状態データを返すように queryFirebase 関数と queryDevice 関数を更新します。

index.js

const queryFirebase = async (deviceId) => {
  const snapshot = await firebaseRef.child(deviceId).once('value');
  const snapshotVal = snapshot.val();
  return {
    on: snapshotVal.OnOff.on,
    isPaused: snapshotVal.StartStop.isPaused,
    isRunning: snapshotVal.StartStop.isRunning,
  };
};

const queryDevice = async (deviceId) => {
  const data = await queryFirebase(deviceId);
  return {
    on: data.on,
    isPaused: data.isPaused,
    isRunning: data.isRunning,
    currentRunCycle: [{
      currentCycle: 'rinse',
      nextCycle: 'spin',
      lang: 'en',
    }],
    currentTotalRemainingTime: 1212,
    currentCycleRemainingTime: 301,
  };
};

EXECUTE インテントを処理する

EXECUTE インテントは、デバイスの状態を更新するコマンドを処理します。レスポンスが返すのは、各コマンドのステータス（SUCCESS、ERROR、PENDING など）と更新後のデバイスの状態です。

functions/index.js で、更新が必要なトレイトのリストと各コマンドの対象デバイスのセットを処理するよう EXECUTE ハンドラを編集します。

index.js

app.onExecute(async (body) => {
  const {requestId} = body;
  // Execution results are grouped by status
  const result = {
    ids: [],
    status: 'SUCCESS',
    states: {
      online: true,
    },
  };

  const executePromises = [];
  const intent = body.inputs[0];
  for (const command of intent.payload.commands) {
    for (const device of command.devices) {
      for (const execution of command.execution) {
        executePromises.push(
            updateDevice(execution, device.id)
                .then((data) => {
                  result.ids.push(device.id);
                  Object.assign(result.states, data);
                })
                .catch(() => functions.logger.error('EXECUTE', device.id)));
      }
    }
  }

  await Promise.all(executePromises);
  return {
    requestId: requestId,
    payload: {
      commands: [result],
    },
  };
});

コマンドと対象デバイスごとに、リクエストされたトレイトに対応する Realtime Database の値を更新します。該当する Firebase 参照を更新して更新後のデバイスの状態を返すように updateDevice 関数を変更します。

index.js

const updateDevice = async (execution, deviceId) => {
  const {params, command} = execution;
  let state; let ref;
  switch (command) {
    case 'action.devices.commands.OnOff':
      state = {on: params.on};
      ref = firebaseRef.child(deviceId).child('OnOff');
      break;
    case 'action.devices.commands.StartStop':
      state = {isRunning: params.start};
      ref = firebaseRef.child(deviceId).child('StartStop');
      break;
    case 'action.devices.commands.PauseUnpause':
      state = {isPaused: params.pause};
      ref = firebaseRef.child(deviceId).child('StartStop');
      break;
  }

  return ref.update(state)
      .then(() => state);
};

6. アクションをテストする

3 つのインテントをすべて実装したら、アクションで洗濯機を制御できるかどうかをテストします。

Firebase にデプロイする

Firebase CLI を使用して、更新したクラウドフルフィルメントをデプロイします。

firebase deploy --only functions

洗濯機をテストする

スマートフォンで以下の音声コマンドを試して、値が変化することを確認します。

「OK Google, 洗濯機をオンにして。」

「OK Google, 洗濯機を一時停止して。」

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

また、洗濯機の現在の状態を確認することもできます。

「OK Google, 洗濯機はオンになってる？」

「OK Google, 洗濯機は動いてる？」

「OK Google, 洗濯機の今のステップを教えて」

これらのクエリやコマンドは、Firebase コンソールの [関数] セクションの関数の下に表示されるログで確認できます。Firebase ログの詳細については、ログの書き込みと表示をご覧ください。

これらのクエリとコマンドは、Google Cloud コンソールで [ロギング] > [ログエクスプローラ] に移動することもできます。Cloud Logging でイベントログにアクセスするで、Google Cloud Logging の詳細を確認する。

7. Google に更新情報を報告する

以上でクラウドサービスとスマートホームインテントの統合がすべて完了し、洗濯機デバイスの現在の状態の制御とクエリの実行ができるようになりました。ただし、サービスがアシスタントにイベント情報（デバイスのプレゼンスや状態の変化など）を自動的に送信する手段がまだ実装されていません。

Request Sync を使用すると、ユーザーがデバイスを追加または削除したとき、またはデバイスの機能が変更されたときに、新しい同期リクエストをトリガーできます。Report State を使用すると、ユーザーが物理的にデバイスの状態（照明のスイッチの点灯など）を変更したり、別のサービスを使用して状態を変更したりしたときに、クラウドサービスからその状態を積極的にホームグラフに送信できるようになります。

このセクションでは、フロントエンドのウェブアプリからこれらのメソッドを呼び出すためのコードを追加します。

HomeGraph API を有効にする

HomeGraph API は、ユーザーのホームグラフ内のデバイスとその状態の保存と照会を可能にします。この API を使用するには、まず Google Cloud コンソールを開き、HomeGraph API を有効にする必要があります。

Google Cloud Console でアクションの <project-id>. に一致するプロジェクトを選択し、HomeGraph API の [API ライブラリ] 画面で [有効にする]をクリックします。

Report State を有効にする

Realtime Database への書き込みによって、スタータープロジェクトの reportstate 関数がトリガーされます。データベースに書き込まれたデータをキャプチャして Report State 経由でホームグラフに送信するよう、functions/index.js の reportstate 関数を更新します。

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      functions.logger.info('Firebase write event triggered Report State');
      const snapshot = change.after.val();

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
              [context.params.deviceId]: {
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      functions.logger.info('Report state response:', res.status, res.data);
    });

Request Sync を有効にする

フロントエンドウェブ UI のアイコンを更新すると、スタータープロジェクトの requestsync 関数がトリガーされます。functions/index.js の requestsync 関数に、HomeGraph API の呼び出しを実装します。

index.js

exports.requestsync = functions.https.onRequest(async (request, response) => {
  response.set('Access-Control-Allow-Origin', '*');
  functions.logger.info(`Request SYNC for user ${USER_ID}`);
  try {
    const res = await homegraph.devices.requestSync({
      requestBody: {
        agentUserId: USER_ID,
      },
    });
    functions.logger.info('Request sync response:', res.status, res.data);
    response.json(res.data);
  } catch (err) {
    functions.logger.error(err);
    response.status(500).send(`Error requesting sync: ${err}`);
  }
});

Firebase にデプロイする

Firebase CLI を使用して、更新したコードをデプロイします。

firebase deploy --only functions

実装をテストする

ウェブ UI の [更新 ] ボタンをクリックし、Firebase コンソールのログに同期リクエストが表示されていることを確認します。

次に、フロントエンドウェブ UI で洗濯機の属性を調整し、[Update] をクリックします。状態の変化が Google に報告されていることを Firebase コンソールのログで確認します。

8. 完了

これで完了です。スマートホームアクションを使用するデバイスクラウドサービスとアシスタントの統合が完了しました。

詳細

さらに詳しく学びたい方は、以下のことをお試しください。

デバイスにmodesと切り替えを追加します。
サポートされているトレイトをデバイスに追加します。
スマートホームのローカル実行を確認する。
詳細については、GitHub サンプルをご覧ください。

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

スマートホーム デバイスを Google アシスタントにリンクする

1. 始める前に

前提条件

作成するアプリの概要

演習内容

必要なもの

2. はじめに

アクティビティ管理を有効にする

Actions プロジェクトを作成する

スマートホーム アプリを選択する

Firebase CLI をインストールする

3.スターター アプリを実行する

ソースコードを取得する

プロジェクトについて

Firebase に接続する

Firebase プロジェクトを設定する

Firebase にデプロイする

Actions Console プロジェクトを構成する

4. 洗濯機を作成する

SYNC レスポンスを更新する

index.js

Firebase にデプロイする

Google アシスタントにリンクする

5. コマンドとクエリを処理する

QUERY インテントを処理する

index.js

index.js

EXECUTE インテントを処理する

index.js

index.js

6. アクションをテストする

Firebase にデプロイする

洗濯機をテストする

7. Google に更新情報を報告する

HomeGraph API を有効にする

Report State を有効にする

index.js

Request Sync を有効にする

index.js

Firebase にデプロイする

実装をテストする

8. 完了

詳細

スマートホームデバイスを Google アシスタントにリンクする

スマートホームアプリを選択する

3.スターターアプリを実行する