Webhook 呼び出しでは、ホームグラフに基づく同じ世帯の複数のセッションについて、パラメータ値をホーム ストレージに保存できます。アクションは、保存された値を後でプロンプトや条件で使用できます。また、Webhook コードは、必要に応じて特定の世帯のホーム ストレージの値にアクセスできます。
ホーム ストレージの状態は app.handle()
リクエストで渡され、home
オブジェクトに格納されます。
制限事項
ホーム ストレージはホームグラフの一部ではないため、モバイル デバイスでは使用できません。Webhook コードで、HOME_STORAGE
デバイス機能を使用し、ユーザーのデバイスの機能に基づいてビジネス ロジックを分岐します。
ホーム ストレージを使用するには、有効にする必要があります。
- Actions Console で、[デプロイ] > [ディレクトリ情報] に移動します。
- [その他の情報] セクションで、[ホーム ストレージ] のチェックボックスをオンにします。
家のデータの読み取りと書き込み
ホーム ストレージの値を更新または設定するには、Webhook 呼び出しで home
オブジェクトの params
フィールドに値を割り当てます。次の例では、ホーム ストレージで「exampleColor」を「red」に設定しています。
Node.js
// Assign color to home storage app.handle('storeColor', conv => { let color = 'red'; conv.home.params.exampleColor = color; });
JSON
{ "responseJson": { "session": { "id": "1234567890123456789", "params": {} }, "prompt": { "override": false }, "home": { "params": { "exampleColor": "red" } } } }
ホーム ストレージに保存されているデータにアクセスするには、Webhook 呼び出しで変数にそのデータを代入します。次の例では、ホーム ストレージの「exampleColor」から値を取得しています。
Node.js
// Retrieve color from home storage app.handle('getStoredColor', conv => { let color = conv.home.params.exampleColor; });
JSON
{ "responseJson": { "session": { "id": "1234567890123456789", "params": {} }, "prompt": { "override": false }, "home": { "params": { "homeColor": "red" } } } }
以前に保存した値を消去するには、Webhook 呼び出しで値を null
に設定します。次の例では、ホーム ストレージの「exampleColor」の値を消去します。
Node.js
// Clear color from home storage app.handle('clearStoredColor', conv => { conv.home.params.exampleColor = null; });
JSON
{ "responseJson": { "session": { "id": "1234567890123456789", "params": {} }, "prompt": { "override": false }, "home": { "params": {} } } }
プロンプト内で保存済み値を参照する
ホーム ストレージに保存されている値はプロンプトで参照できます。値を参照するには、$home.params.PARAMETER_NAME
構文を使用します。ここで、PARAMETER_NAME
はパラメータの設定時に Webhook で指定される名前です。
たとえば、以前にパラメータ exampleColor
として色の値をホーム ストレージに保存していました。プロンプトでその値にアクセスするには、$home.params.exampleColor
を使用してその値を参照します。
JSON
{ "candidates": [{ "first_simple": { "variants": [{ "speech": "Your favorite color is $home.params.exampleColor." }] } }] }
条件内で保存された値を参照する
また、ホーム ストレージに保存されている値をconditionsで参照することもできます。値を参照するには、home.params.PARAMETER_NAME
構文を使用します。ここで、PARAMETER_NAME
はパラメータの設定時に Webhook で指定される名前です。
たとえば、以前にホーム ストレージに色の値をパラメータ exampleColor
として保存し、それを条件で値「red」と一致させたいとします。条件では、home.params.exampleColor
を使用して保存済み値を参照します。条件式は次のようになります。
条件の構文
home.params.exampleColor == "red"
ホーム ストレージ データの有効期限
アクションが呼び出されないまま 90 日経過すると、ホーム ストレージのデータはワイプされます。ホームグラフ構造に関連付けられているデバイスでアクションを呼び出すと、90 日間のタイマーがリセットされます。ホームグラフ ストラクチャを削除すると、対応するホーム ストレージ データは消去されます。
ホーム ストレージを使用するアクションの場合、ホームグラフの構造管理者は、アシスタント ディレクトリにあるアクションのページから、管理するストラクチャのホーム ストレージを削除できます。
- ユーザー ストレージを表示または消去するアクションを探して選択します。
- ページの一番下までスクロールします。
- ホーム ストレージに保存されているデータを削除するには、[action_name の記憶を許可しない] をクリックします。
デバイスの管理者がデバイスをストラクチャから分離すると、ホーム ストレージも分離されます。ストラクチャ マネージャーが消去しない限り、ホーム ストレージ データは、ストラクチャ マネージャーが変更された場合でも、デバイスに関連付けられたままになります。
シミュレーターに表示される家のストレージ データ
Actions Console のシミュレータを使用してアクションをテストする場合、ホーム ストレージに保存されているデータの動作は、実機とわずかに異なります。シミュレータは独自のホームグラフの一部とみなされるため、ネットワーク内にある他のデバイスにはデータは保持されません。また、[Simulate 未確認ユーザー] シミュレータの設定が有効になっていると、ホーム ストレージ データはセッション間で保持されません。
やり取りの例
ログイン ユーザーのアクションの初回呼び出し時のインタラクションの例を次に示します。
ユーザーのクエリ | OK Google, ExampleAction に話しかけて。 |
---|---|
アシスタントの応答 | ExampleAction を使ってみましょう。 |
アシスタントの応答 | なお、ExampleAction はプレイするたびに保存されるため、家族の他のメンバーが中断したところから再開できます。 |
ExampleAction レスポンス | 確認済みのお客様、あなたはレベル 0 です。「次へ」または「リセットする」または「キャンセル」と言ってください。 |
ユーザーのクエリ | 次へ] をクリックします。 |
ExampleAction レスポンス | あなたはレベル 1 です。 |
ユーザーのクエリ | 退出] をタップします。 |
その後、しばらくして同じ確認済みユーザーがアクションに戻った場合:
ユーザーのクエリ | OK Google, ExampleAction に話しかけて。 |
---|---|
アシスタントの応答 | ExampleAction を使ってみましょう。 |
ExampleAction レスポンス | 確認済みのお客様、あなたはレベル 1 です。「次へ」または「リセットする」または「キャンセル」と言ってください。 |
ユーザーのクエリ | 次へ] をクリックします。 |
ExampleAction レスポンス | あなたはレベル 2 です。 |
ユーザーのクエリ | 退出] をタップします。 |
翌日、未確認のユーザーが(ホームグラフで指定されているとおりに)同じ世帯の別のデバイスでアクションを操作します。
ユーザーのクエリ | OK Google, ExampleAction に話しかけて。 |
---|---|
アシスタントの応答 | ExampleAction を使ってみましょう。 |
アシスタントの応答 | なお、ExampleAction はプレイするたびに保存されるため、家族の他のメンバーが中断したところから再開できます。 |
ExampleAction レスポンス | ゲストユーザー様あなたはレベル 2 です。「次へ」または「リセットする」または「キャンセル」と言ってください。 |
ユーザーのクエリ | 次へ] をクリックします。 |
ExampleAction レスポンス | レベル 3 になりました。 |
ユーザーのクエリ | 退出] をタップします。 |