在 Webhook 呼叫中,您可以將參數值儲存在同一個住家的多個工作階段中 (以家用圖表為基礎)。這樣一來,您的操作之後就可以在提示和條件中使用這些儲存的值,而您的 Webhook 程式碼也可以視需要存取特定家庭的住家儲存空間值。
首頁儲存空間的狀態會透過 app.handle()
要求傳遞,並儲存在 home
物件中。
限制
行動裝置無法與家用裝置搭配使用,因為這些裝置不是 Home 圖表的一部分。在 Webhook 程式碼中,使用 HOME_STORAGE
裝置功能來根據使用者裝置的能力建立商業邏輯。
您必須啟用家用儲存空間:
- 在 Actions 主控台,依序前往「Deploy」(部署) >「Directory info」(目錄資訊)。
- 在「其他資訊」區段中,勾選「住家儲存空間」方塊。
讀取及寫入家庭資料
如要更新或設定家用儲存空間的新值,請在 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." }] } }] }
在條件下參照儲存的值
您也可以在條件中參照儲存在住家儲存空間中的值。如要參照這個值,請使用 home.params.PARAMETER_NAME
語法,其中 PARAMETER_NAME
是設定參數時在 Webhook 中指定的名稱。
例如,您之前已將顏色值儲存在家用儲存空間中做為參數 exampleColor
,而您想要在條件中比對值「red」。在條件中,您可以使用 home.params.exampleColor
參照儲存的值。您的條件運算式看起來會像這樣:
條件語法
home.params.exampleColor == "red"
住家儲存空間資料的到期時間
連續 90 天未叫用動作時,系統會清除住家儲存空間資料。在任何與 Home Graph 結構相關的裝置上叫用動作會重設 90 天的計時器。如果刪除 Home Graph 結構,系統會清除對應的家用儲存空間資料。
針對使用住家儲存空間的 Actions,Home Graph 結構管理員可以透過 Assistant 目錄的「Actions」(動作) 頁面,針對自己管理的結構清除住家儲存空間:
- 找出並選取要查看或清除的使用者儲存空間。
- 捲動至頁面底部:
- 如要移除儲存在家庭儲存空間中的資料,請按一下「Stop action_name」(記住我的名稱)。
當裝置的管理員與結構分離時,家用儲存裝置也會分離。除非結構管理員清除裝置資料,否則住家結構體資料會持續與裝置建立關聯。
模擬工具中的住家儲存空間資料
使用 Actions 主控台中的模擬工具測試動作時,儲存在首頁儲存空間的資料運作方式與實體裝置稍有不同。模擬工具會視為自家的家庭圖的一部分,因此資料不會存在您在網路中可能存在的其他裝置。此外,啟用模擬未驗證的使用者模擬工具設定時,各個工作階段的住家儲存空間資料不會保留。
互動示例
以下是已登入使用者在首次叫用動作時的互動範例:
使用者查詢內容。 | Ok Google,和 |
---|---|
Google 助理回應 | 取得 ExampleAction。 |
Google 助理回應 | 提醒你,每次執行遊戲時,ExampleAction 都會儲存資料,以便住家中的其他人接續之前的進度。 |
ExampleAction 回應 | 已驗證的使用者。你是第 0 級。說出「繼續」、「重設」或「取消」。 |
使用者查詢內容。 | 。 |
ExampleAction 回應 | 你是第 1 級。 |
使用者查詢內容。 | Leave. |
之後經過相同的已驗證使用者返回「動作」動作後:
使用者查詢內容。 | Ok Google,和 |
---|---|
Google 助理回應 | 取得 ExampleAction。 |
ExampleAction 回應 | 已驗證的使用者。你是第 1 級。說出「繼續」、「重設」或「取消」。 |
使用者查詢內容。 | 。 |
ExampleAction 回應 | 你是第 2 級。 |
使用者查詢內容。 | Leave. |
第二天,未驗證的使用者與同一住家中的另一部裝置 (如 Home Graph 所指定) 上的動作互動。
使用者查詢內容。 | Ok Google,和 |
---|---|
Google 助理回應 | 取得 ExampleAction。 |
Google 助理回應 | 提醒你,每次執行遊戲時,ExampleAction 都會儲存資料,以便住家中的其他人接續之前的進度。 |
ExampleAction 回應 | 訪客使用者您好!你是第 2 級。說出「繼續」、「重設」或「取消」。 |
使用者查詢內容。 | 。 |
ExampleAction 回應 | 你是第 3 級。 |
使用者查詢內容。 | Leave. |