本頁面由 Cloud Translation API 翻譯而成。

將資料儲存在對話中 (Dialogflow)

提供絕佳的使用者體驗，通常是能在對話期間或與使用者的多次對話之間儲存資料。如果您在單一對話中提供實用的獎勵、在工作階段中儲存遊戲分數，或記住使用者少量資訊，這項功能就能派上用場。

視您是否需要在對話中或跨對話儲存資料而定，需求會略有不同。如要在對話中儲存資料，您可以使用 AppResponse 物件的 conversationToken 欄位。

如要儲存對話資料，請改為按照下列步驟操作：

確認使用者是否通過驗證。
使用 AppResponse 物件的 userStorage 欄位儲存或存取使用者資料。

儲存對話期間間的資料

conversationToken 欄位是包含不透明符記，這個字串會在每次對話回流後循環至動作。例如，如果您將 AppResponse 的值設為對話的第一次轉場，則針對對話的第二次轉彎所收到的 AppRequest 在其 conversationToken 中會包含 "count=1"。

且在對話開始時，權杖一律會初始化為空白字串。如果您使用 Actions on Google Node.js 用戶端程式庫，則可使用 conv.data 將對話符記與 JSON 物件搭配使用，其中 conv 是 Conversation 的執行個體。

以下範例說明如何在 AppResponse 的 conversationToken 欄位中儲存計數器：

Node.js

conv.data.firstNum = firstNum;
conv.ask(`Got it, the first number is ${firstNum}.`);
conv.ask(`What's the second number?`);index.js

Java

ResponseBuilder responseBuilder = getResponseBuilder(request);
responseBuilder.getConversationData().put("firstNum", firstNum);
responseBuilder.add("Got it, the first number is " + firstNum + ".");
responseBuilder.add("What's the second number?");
return responseBuilder.build();MyActionsApp.java

JSON

請注意，以下 JSON 說明使用 outputContexts 而非 conversationToken。

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Got it, the first number is 23."
            }
          },
          {
            "simpleResponse": {
              "textToSpeech": "What's the second number?"
            }
          }
        ]
      }
    }
  },
  "outputContexts": [
    {
      "name": "projects/save-data-df-js/agent/sessions/ABwppHGfFkWJdHKPpBEYiGkhdoakWmYj_2sZa4o8pbGG9nj4q5_GfDTtNEXOY34mLX8G4o_d7oZdUW9bnBZC/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{\"firstNum\":23}"
      }
    }
  ]
}

JSON

請注意，以下 JSON 說明的是 Webhook 回應。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Got it, the first number is 23."
              }
            },
            {
              "simpleResponse": {
                "textToSpeech": "What's the second number?"
              }
            }
          ]
        }
      }
    }
  ],
  "conversationToken": "{\"data\":{\"firstNum\":23}}"
}

如需實際使用範例，請參閱提供實用的提示，並順利執行。

儲存對話的資料

AppResponse 物件的 userStorage 欄位是字串，其中包含由特定使用者的對話中儲存的動作提供的不透明權杖。例如，遊戲可以在 userStorage 中儲存使用者的最高分數，並在使用者每次開始新對話時在歡迎訊息中使用其值。

判斷及處理使用者驗證狀態

使用者的驗證狀態可以是 GUEST 或 VERIFIED 的值。每次開始對話時，Actions on Google 會根據對話開始時，根據各種指標設定使用者的驗證狀態。例如，使用者在行動裝置上登入 Google 助理時，驗證驗證狀態為 VERIFIED。

以下列舉幾個驗證狀態可能是使用者處於 GUEST 狀態的原因：

使用者已關閉個人化搜尋結果。
使用者停用了網路和應用程式活動。請注意，部分使用者可能在網域層級停用了這項設定。
如果裝置已啟用 Voice Match 功能，但比對失敗，或是使用者未啟動語音就能叫用 Google 助理 (例如長按 Google Home)。
使用者未登入。

請一律先檢查使用者的驗證狀態，再使用 userStorage 儲存資料，或是啟動帳戶連結流程，防止訪客使用者使用會失敗的功能。

如果您使用 Actions on Google 用戶端程式庫，適用於 Node.js，可以使用 conv.user.storage 以使用者儲存空間的形式以 JSON 物件的形式，其中 conv 是 Conversation 的執行個體。以下範例說明如何將計數器儲存在 AppResponse 的 userStorage 欄位中：

Node.js

app.intent('Save Sum', (conv) => {
  if (conv.user.verification === 'VERIFIED') {
    conv.user.storage.sum = conv.data.sum;
    conv.close(`Alright, I'll store that for next time. See you then.`);
  } else {
    conv.close(`I can't save that right now, but we can add ` +
      `new numbers next time!`);
  }
});index.js

Java

@ForIntent("Save Sum")
public ActionResponse saveSum(ActionRequest request) {
  ResponseBuilder responseBuilder = getResponseBuilder(request);
  Integer sum = ((Double) request.getConversationData().get("sum")).intValue();
  String verificationStatus = request.getUser().getUserVerificationStatus();
  if (verificationStatus.equals("VERIFIED")) {
    responseBuilder.getUserStorage().put("sum", sum);
    responseBuilder.add("Alright, I'll store that for next time. See you then.");
  } else {
    responseBuilder.add("I can't save that right now, but we can add new numbers next time!");
  }
  responseBuilder.endConversation();
  return responseBuilder.build();
}MyActionsApp.java

Node.js

if (conv.user.verification === 'VERIFIED') {
  conv.user.storage.sum = conv.data.sum;
  conv.close(`Alright, I'll store that for next time. See you then.`);
} else {
  conv.close(`I can't save that right now, but we can add ` +
    `new numbers next time!`);
}index.js

Java

ResponseBuilder responseBuilder = getResponseBuilder(request);
Integer sum = ((Double) request.getConversationData().get("sum")).intValue();
String verificationStatus = request.getUser().getUserVerificationStatus();
if (verificationStatus.equals("VERIFIED")) {
  responseBuilder.getUserStorage().put("sum", sum);
  responseBuilder.add("Alright, I'll store that for next time. See you then.");
} else {
  responseBuilder.add("I can't save that right now, but we can add new numbers next time!");
}
responseBuilder.endConversation();
return responseBuilder.build();MyActionsApp.java

JSON

請注意，以下 JSON 說明的是 Webhook 回應。

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Alright, I'll store that for next time. See you then."
            }
          }
        ]
      },
      "userStorage": "{\"data\":{\"sum\":68}}"
    }
  }
}

JSON

請注意，以下 JSON 說明的是 Webhook 回應。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Alright, I'll store that for next time. See you then."
          }
        }
      ]
    }
  },
  "conversationToken": "{\"data\":{\"firstNum\":23,\"sum\":68}}",
  "userStorage": "{\"data\":{\"sum\":68}}"
}

如需實際使用範例，請參閱依據使用者的偏好設定個人化對話。

法律聲明：取得 userStorage 前，請先取得使用者同意。 有些國家/地區的法規要求開發人員必須取得使用者的同意，才能存取或儲存特定資訊 (例如個人資訊)。userStorage如果您在上述任一國家/地區營運，且想要在 userStorage 中存取或儲存這類資訊，則必須使用確認協助向使用者徵求同意並取得同意聲明，才能開始在 userStorage 中儲存這類資訊。

使用者儲存空間到期日

當 Google 助理比對使用者與使用者時，userStorage 的內容永遠不會過期，且只有使用者或動作本身可以清除。

當 Google 助理無法比對使用者的身分時，系統就會在對話結束時清除 userStorage 的內容。以下列舉幾種 Google 助理無法比對使用者身分與使用者的情況：

已設定 Voice Match，但找不到相符項目。
使用者已停用個人資料。

清除 userStorage 欄位的內容

如要清除動作 userStorage 欄位的內容，請將 AppResponse 的 resetUserStorage 欄位設為 true。如果將 userStorage 的值設為空字串，userStorage 的值在下次對話時不會變更。如此一來，您就無需在其內容未變更的情況下，將整個 userStorage 回傳回來。

如果您使用 Actions on Google 用戶端程式庫，適用於 Node.js，可以直接將 conv.user.storage 的值設為 {} (空白物件)。

Node.js

app.intent('Forget Number', (conv) => {
  conv.user.storage = {};
  conv.ask(`Alright, I forgot your last result.`);
  conv.ask(`Let's add two new numbers. What is the first number?`);
});index.js

Java

@ForIntent("Forget Number")
public ActionResponse forgetNumber(ActionRequest request) {
  ResponseBuilder responseBuilder = getResponseBuilder(request);
  responseBuilder.getUserStorage().clear();
  responseBuilder.add("Alright, I forgot your last result.");
  responseBuilder.add("Let's add two new numbers. What is the first number?");
  return responseBuilder.build();
}MyActionsApp.java

Node.js

conv.user.storage = {};
conv.ask(`Alright, I forgot your last result.`);
conv.ask(`Let's add two new numbers. What is the first number?`);index.js

Java

ResponseBuilder responseBuilder = getResponseBuilder(request);
responseBuilder.getUserStorage().clear();
responseBuilder.add("Alright, I forgot your last result.");
responseBuilder.add("Let's add two new numbers. What is the first number?");
return responseBuilder.build();MyActionsApp.java

JSON

請注意，以下 JSON 說明的是 Webhook 回應。

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Alright, I forgot your last result."
            }
          },
          {
            "simpleResponse": {
              "textToSpeech": "Let's add two new numbers. What is the first number?"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}"
    }
  }
}

JSON

請注意，以下 JSON 說明的是 Webhook 回應。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Alright, I forgot your last result."
              }
            },
            {
              "simpleResponse": {
                "textToSpeech": "Let's add two new numbers. What is the first number?"
              }
            }
          ]
        }
      }
    }
  ],
  "userStorage": "{\"data\":{}}"
}

身為使用者，您可以在您叫用的動作中查看 userStorage 欄位的內容。您也可以停止服務記住您的資訊，藉此將特定使用者資料儲存在該動作中。

開啟手機上的「Google 助理」應用程式。
輕觸導覽匣圖示。
在「探索」分頁中，找出您要查看或清除使用者儲存空間的動作，然後輕觸該項目以開啟詳細資料頁面。
捲動至頁面底部。
- 如要查看 userStorage 欄位的內容，請輕觸 [[查看儲存的資料]。
- 如要移除已儲存的使用者資料，請輕觸 [不要記住「$$action」。

將資料儲存在對話中 (Dialogflow)

在 Dialogflow 中探索

儲存對話期間間的資料

Node.js

Java

JSON

JSON

儲存對話的資料

判斷及處理使用者驗證狀態

Node.js

Java

Node.js

Java

JSON

JSON

使用者儲存空間到期日

清除 userStorage 欄位的內容

Node.js

Java

Node.js

Java

JSON

JSON