家庭儲存空間

在 Webhook 呼叫中,您可以將參數值儲存在同一個家庭儲存空間中的多個工作階段 (根據 Home Graph)。如此一來,您的動作之後便能在提示和條件中使用這些儲存的值,而您的 Webhook 程式碼可在必要時存取住家儲存空間中的值。

首頁儲存空間的狀態會透過 app.handle() 要求傳遞,並儲存在 home 物件中。

限制

住家儲存空間無法與行動裝置搭配使用,因為這些裝置不屬於 Home Graph 的一部分。在 Webhook 程式碼中,使用 HOME_STORAGE 裝置功能根據使用者裝置具備的功能來分支商業邏輯。

您必須選擇啟用住家儲存空間:

  1. 在 Actions 控制台中,依序前往「Deploy」(部署) >「Directory information」(目錄資訊)
  2. 在「其他資訊」部分,勾選「住家儲存空間」方塊。

在家庭中讀取及寫入資料

如要在家用儲存空間中更新或設定新的值,請在 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 天未叫用動作,住家儲存空間資料就會抹除。只要在與 Home Graph 結構相關聯的任何裝置上叫用動作,就會重設 90 天的計時器。如果刪除 Home Graph 結構,對應的住家儲存空間資料也會清除。

對於使用主儲存空間的動作,Home Graph 結構管理員可以透過 Assistant 目錄中的動作頁面,清除所管理結構的主儲存空間:

  1. 找出並選取要查看的動作,或是清除使用者儲存空間的動作。
  2. 捲動至頁面底部:
    • 如要移除儲存在住家儲存空間中的資料,請按一下「Stop action_name」(停止記住我)

當裝置管理員與住家結構體解除關聯時,住家儲存空間也會解除關聯。即使結構管理員有所變更,住家儲存空間資料仍會持續與裝置建立關聯。

模擬工具的住家儲存空間資料

使用動作主控台中的模擬工具測試動作時,儲存在家用儲存空間中的資料行為會與實體裝置稍有不同。模擬工具會視為本身首頁圖譜的一部分,因此資料無法保留給網路上可能擁有的其他裝置。此外,如果啟用了「模擬未經驗證的使用者」模擬工具設定,主工作階段儲存空間資料也不會保留每個工作階段。

互動範例

以下是已登入的使用者首次叫用動作時的互動範例:

使用者查詢內容。 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.