定義、參照、設定及取得參數
參數有四種一般用途：
- 在設計階段定義：在設計階段，您可以使用控制台或 API 定義參數。舉例來說，您可以定義意圖參數，並在訓練詞組中使用，指出應擷取的使用者輸入內容。
- 設計階段參照：參數參照是保留參數值的變數，會在執行階段擷取。在設計階段，您可以使用控制台或 API 參照各種資料類型的參數。舉例來說，您可以在路徑的靜態 fulfillment 回覆中參照工作階段參數。
- 在執行階段設定：在執行階段，Dialogflow CX 服務、呼叫 API 的服務，以及 Webhook 服務都可以設定參數值。舉例來說，當使用者輸入內容與意圖相符，且輸入內容包含參數資料時，Dialogflow CX 服務會設定意圖參數的值。
- 在執行階段取得：在執行階段，參數參照會包含已設定的參數值，您可以使用 API 或 Webhook 取得參數值。舉例來說，當比對到意圖並呼叫 Webhook 時，Webhook 服務會收到意圖的參數值。
參數命名
參數命名規則如下：
- 請使用下列字元：
[A-Z]、[a-z]、[0-9]、.、-、_ - 參數名稱不區分大小寫，因此 Dialogflow CX 會將
Apple和apple視為相同參數。Webhook 和 API 用戶端程式碼也應將參數名稱視為不區分大小寫，因為 Dialogflow CX 傳回的參數名稱不保證大小寫。 - 在不同意圖或表單中建立具有相同 ID 或顯示名稱的參數時，請確保所有定義的實體類型和其他設定都相同。如果實體類型或其他參數設定不同，請為每個定義使用不重複的參數 ID 或顯示名稱。
參數值類型
參數值支援多種值類型。以下工作階段一節說明如何參照各個參數值類型。mapTypeId 支援的類型如下：
| 類型 | 說明 |
|---|---|
| 純量 | 單一數值或字串值。 |
| 複合 | JSON 物件，透過比對複合實體或填入意圖參數填入，其中包含 original 和 resolved 欄位。 |
| 清單 | 為設為清單的參數填入的純量或複合值清單。請參閱下列「Is List」選項。 |
參數空字串和空值
您可以將字串參數值設為 ""，這會將參數設為空字串。
您可以將任何參數值設為 null，表示尚未設定該參數。
參數原始值
在執行階段，如果文字與特定實體相符，通常會解析為更方便處理的值。舉例來說，使用者輸入內容中的「apples」一詞，可能會解析為水果實體的「apple」。
只有工作階段參數參照的複合值類型可以參照原始值。
意圖參數
意圖會使用參數，在意圖相符時擷取使用者提供的資料。意圖參數是由下列資料定義：
- 名稱 (也稱為 ID 或顯示名稱)： 用於識別參數的名稱。
- 實體類型：與參數相關聯的實體類型。
- Is List：如果設為 true，系統會將參數視為值清單。
- Redact in log：如果設為 true，系統會遮蓋使用者提供的參數資料。
定義意圖參數
參考意圖參數
意圖參數參照可用於意圖路徑的靜態執行要求回覆訊息。
您可以參照原始值或解析值。
如要參照目前相符意圖的參數，請使用下列其中一種格式：
$intent.params.parameter-id.original $intent.params.parameter-id.resolved
舉例來說，如果參數 ID 為 date，則可將解析值參照為 $intent.params.date.resolved。
設定意圖參數
在執行階段，當使用者輸入內容與意圖相符時，Dialogflow CX 會設定相關聯訓練詞組的註解所使用的任何參數。
意圖路徑的執行要求可以使用執行要求參數預設集，在執行階段設定意圖參數值。
取得意圖參數
在比對到意圖的對話回合中，程式碼可以存取意圖參數值。
與 API 互動會傳回意圖參數值。請參閱 detectIntent 方法的 queryResult.parameters 回應欄位，瞭解 Session 類型。
選取工作階段參考資料的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 工作階段資源 | 工作階段資源 |
| RPC | 工作階段介面 | 工作階段介面 |
| C++ | SessionsClient | 不適用 |
| C# | SessionsClient | 不適用 |
| Go | SessionsClient | 不適用 |
| Java | SessionsClient | SessionsClient |
| Node.js | SessionsClient | SessionsClient |
| PHP | 不適用 | 不適用 |
| Python | SessionsClient | SessionsClient |
| 小茹 | 不適用 | 不適用 |
Webhook 會接收意圖參數值。請參閱 Webhook 要求中的 intentInfo.parameters 欄位。
表單參數
您可以為每個頁面定義表單，也就是應從使用者收集的參數清單。代理會與使用者進行多輪對話，直到收集到所有必要的表單參數 (也稱為頁面參數)。代理會按照頁面定義的順序收集這些參數。針對每個必要表單參數，您也需要提供提示，讓代理向使用者要求該資訊。這項程序稱為表單填寫。
舉例來說，您可以建立表單，收集 Collect Customer Info 頁面使用者的姓名和電話號碼。
下列資料用於定義表單參數：
| 控制台選項名稱 | API 欄位鏈 | 說明 |
|---|---|---|
| 顯示名稱 | Page.form.parameters[].displayName |
用於識別參數的名稱。 |
| 實體類型 | Page.form.parameters[].entityType |
與參數相關聯的實體類型。 |
| 必填 | Page.form.parameters[].required |
表示是否一定要有參數，表單填寫完畢前，必須填寫必要參數，代理會提示使用者輸入值。詳情請參閱下方的「設定表單參數」一節。 |
| 預設值 (只有在未勾選「必填」時才會顯示) | Page.form.parameters[].defaultValue |
選用參數的預設值。詳情請參閱下方的「設定表單參數」一節。 |
| 是清單 | Page.form.parameters[].isList |
如果為 true，參數會視為值清單。 |
| 在記錄中遮蓋 | Page.form.parameters[].redact |
如果設為 true，系統會遮蓋使用者提供的參數資料。 |
| 初始提示詞執行要求 | Page.form.parameters[].fillBehavior.initialPromptFulfillment |
以執行要求形式呈現的初始提示，用於向使用者要求必要參數值。詳情請參閱下方的「設定表單參數」一節。 |
| 再次提示事件處理常式 | Page.form.parameters[].fillBehavior.repromptEventHandlers |
如果代理無法填入參數，就會使用這些提示，再次要求使用者提供參數。請參閱「表單填寫重新提示處理常式」。如果未定義重新提示事件處理常式，代理會在嘗試失敗後，使用初始提示再次提示。 |
| DTMF | 無法使用 | 請參閱下方的「DTMF」一節。 |
定義及管理表單參數
表單參數是在設計階段建立頁面時定義。
如要使用控制台變更表單參數順序，請按一下頁面上的「Parameters」(參數) 區段標題，然後拖曳參數表格中的參數列。
如要刪除表單參數，請按一下頁面上的「Parameters」(參數) 區段標題，將滑鼠游標懸停在參數上，然後按一下「Delete」(刪除) 按鈕 delete。
參考表單參數
表單參數參照不會直接使用。您只能檢查個別表單參數或整個表單的填寫狀態。您可以在條件路徑的條件規定中使用這些表單狀態參照。
如要檢查目前頁面的完整表單是否已填寫，請使用下列條件：
$page.params.status = "FINAL"
如要檢查上一個回合是否填寫了特定表單參數，請使用下列條件：
$page.params.parameter-id.status = "UPDATED"
設定表單參數
表單參數值可透過多種方式設定。以下各子節將說明設定表單參數值的機制。
預設參數值
您可以為選用的表單參數提供預設值。表單填寫開始時，所有未設定的選用表單參數都會設為預設值。這些值可透過下列部分機制初始化或覆寫。
如果參數為必要，系統會忽略其預設值。
填寫表單
Dialogflow CX 會自動設定使用者在填寫表單時提供的參數值。代理會按照頁面定義的順序收集必要參數。代理會使用您為每個必要參數提供的初始提示執行要求，提示使用者輸入必要值。選用參數不會觸發提示。
如果使用者在代理提示後未提供必要參數值，系統會重複初始提示，除非重新提示處理常式中定義了其他行為。如果定義了多個初始文字提示詞，代理的行為會與任何執行文字回覆相同。
意圖和工作階段參數傳播
在執行階段設定任何類型的參數時，系統會將參數寫入工作階段，並成為工作階段參數。
頁面首次啟用時，以及在啟用期間，任何與工作階段參數同名的表單參數，都會自動設為工作階段參數值。
意圖和工作階段參數傳播是唯一能將選用表單參數設為使用者輸入值的機制，但這項機制也能設定或覆寫必要表單參數值。
執行參數預設選項
路徑、事件處理常式或表單重新提示的執行要求，可以使用執行要求參數預設值，在執行階段設定表單參數值。執行要求參數預設值會覆寫參數值，包括參數預設值。
Webhook 參數設定
Webhook 可以在執行階段設定表單參數的值。請參閱 Webhook 回應中的 pageInfo.formInfo.parameterInfo 欄位。
取得表單參數
與 API 互動時，系統會傳回表單參數值。請參閱 detectIntent 方法的 queryResult.parameters 回應欄位，瞭解 Session 類型。
選取工作階段參考資料的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 工作階段資源 | 工作階段資源 |
| RPC | 工作階段介面 | 工作階段介面 |
| C++ | SessionsClient | 不適用 |
| C# | SessionsClient | 不適用 |
| Go | SessionsClient | 不適用 |
| Java | SessionsClient | SessionsClient |
| Node.js | SessionsClient | SessionsClient |
| PHP | 不適用 | 不適用 |
| Python | SessionsClient | SessionsClient |
| 小茹 | 不適用 | 不適用 |
Webhook 會接收表單參數值。請參閱 Webhook 要求中的 pageInfo.formInfo.parameterInfo 欄位。
表單填寫重新提示處理常式
重新提示處理常式也稱為參數層級事件處理常式，用於定義必要參數的複雜參數提示行為。舉例來說，如果使用者在初始提示後未提供值，您可以使用重新提示處理常式來變更提示，並在嘗試 N 次失敗後轉換至其他頁面。
如果未定義重新提示處理常式，系統會視需要使用初始提示再次提示使用者。
如果使用者回應非預期的輸入內容，系統會叫用 sys.no-match-* 或 sys.no-input-* 事件，並呼叫為這些事件定義的任何重新提示處理常式。
與其他事件處理常式一樣，再次提示處理常式也是一種狀態處理常式，可設定下列一或兩項：
- 提供使用者再次提示訊息和參數預設值的執行要求。
- 用於變更目前頁面的轉場目標。
工作階段參數
在執行階段設定任何類型的參數時，系統會將參數寫入工作階段，並成為工作階段參數。這些參數在設計階段並未明確定義。在工作階段期間，您隨時可以參照這些工作階段參數。
參考工作階段參數
工作階段參數參照可用於下列執行要求類型的靜態回覆訊息：
- 頁面進入點執行要求
- 路徑出貨
- 事件處理常式執行
- 表單提示詞執行
- 表單重新提示執行
參考資料也可用於：
- 用於驗證的 Webhook 標頭值。
- 彈性 Webhook 要求：用於將參數值傳送至 Webhook。
如要參照工作階段參數，請使用下列格式：
純量
如要存取純量實體類型的參數：
$session.params.parameter-id
舉例來說，如果參數 ID 是 date，則可將值參照為 $session.params.date。
複合
如要存取複合實體類型參數的成員：
$session.params.parameter-id.member-name
舉例來說，如果參數 ID 為
location，您可以將zip-code成員值參照為$session.params.location.zip-code。如要存取複合實體類型參數的原始值：
$session.params.parameter-id.original
如要存取複合實體類型參數的完整物件，請使用 IDENTITY 系統函式。
清單
如要查看完整元素清單，請按照下列步驟操作：
$session.params.parameter-id
舉例來說，如果清單參數 ID 為
colors，且從使用者查詢中擷取的值為["red", "blue", "yellow"]，則可將所有值參照為$session.params.colors。如要存取清單參數的第 i 個元素，請按照下列步驟操作：
$session.params.parameter-id[i]
舉例來說，如果清單參數 ID 為
colors，則可將第一個值參照為$session.params.colors[0]。
設定工作階段參數
表單填寫完成後，Dialogflow CX 會將填寫的參數寫入工作階段。
路徑、事件處理常式或表單重新提示的回應，可以使用預設回應參數，在執行階段設定工作階段參數值。
Webhook 可以在執行階段設定工作階段參數的值。請參閱標準 Webhook 回應中的 sessionInfo.parameters 欄位，或參閱彈性 Webhook 回應。
與 API 互動時，可以設定工作階段參數值。請參閱 Session 類型的 detectIntent 方法 queryParams.parameters 要求欄位。
選取工作階段參考資料的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 工作階段資源 | 工作階段資源 |
| RPC | 工作階段介面 | 工作階段介面 |
| C++ | SessionsClient | 不適用 |
| C# | SessionsClient | 不適用 |
| Go | SessionsClient | 不適用 |
| Java | SessionsClient | SessionsClient |
| Node.js | SessionsClient | SessionsClient |
| PHP | 不適用 | 不適用 |
| Python | SessionsClient | SessionsClient |
| 小茹 | 不適用 | 不適用 |
取得工作階段參數
與 API 互動會傳回工作階段參數值。請參閱 detectIntent 方法的 queryResult.parameters 回應欄位，瞭解 Session 類型。
選取工作階段參考資料的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 工作階段資源 | 工作階段資源 |
| RPC | 工作階段介面 | 工作階段介面 |
| C++ | SessionsClient | 不適用 |
| C# | SessionsClient | 不適用 |
| Go | SessionsClient | 不適用 |
| Java | SessionsClient | SessionsClient |
| Node.js | SessionsClient | SessionsClient |
| PHP | 不適用 | 不適用 |
| Python | SessionsClient | SessionsClient |
| 小茹 | 不適用 | 不適用 |
Webhook 會接收工作階段參數值。請參閱 Webhook 要求中的 sessionInfo.parameters 欄位。
關閉電話語音辨識功能
在吵雜的環境中，語音辨識功能可能會將背景噪音轉錄為使用者輸入內容。如果是電話整合，這些錯誤的轉錄稿可能會觸發不相符事件，或中斷使用者透過鍵盤輸入 DTMF 數字。
如要只接受 DTMF 輸入，請將 telephony_disable_voice_processing 工作階段參數設為 true。從下一個對話回合開始，Dialogflow CX 會忽略語音輸入，只處理 DTMF 輸入。這項設定在工作階段結束前都會有效。如要重新啟用語音辨識功能，請將參數設為 false。
建議您將這個參數做為備用方案，而不是在對話開始時使用。舉例來說，使用者連續觸發兩次不相符或無輸入內容事件後，請使用執行參數預設值將參數設為 true，然後提示使用者使用撥號鍵盤。請確認使用者需要提供的參數已啟用 DTMF。
參數傳播
當使用者輸入內容提供參數值時，參數可能會傳播到其他層級：
- 如果意圖參數是由意圖比對設定，則使用中頁面的同名表單參數會設為相同的值。參數的實體類型由意圖參數定義決定。
- 如果意圖參數是由意圖比對設定，或表單參數是在填寫表單時設定，該參數就會成為工作階段參數。
電話整合的 DTMF
您可以為參數啟用及設定 DTMF (雙音多頻信號)。啟用後，如果代理使用電話整合，使用者就能透過電話撥號鍵盤提供參數值。
為減少歧義，DTMF 輸入可以解讀為一般和 DTMF 專用 (建議) 形式：
- 一般形式是使用者輸入的撥號鍵盤值。例如
123#。 - DTMF 專用表單會將輸入內容轉換為
dtmf_digits_[digits]，其中[digits]是原始 DTMF 數字，*替換為star，#替換為pound。例如，123#會解讀為dtmf_digits_123pound。
比對參數的實體類型時，Dialogflow CX 會嘗試比對一般和 DTMF 專用形式。如果實體類型用於 DTMF 輸入，建議您定義 dtmf_digits_123 等同義詞，以改善 NLU 比對。
如果 DTMF 輸入不符合終止條件 (未達到最大數字長度，或未由結束數字終止)，Dialogflow CX 代理會繼續等待更多輸入。在這段期間，如果觸發無語音逾時，代理會改為叫用無輸入內容事件。如果只偵測到語音語句，代理會比對語音輸入內容。如果同時偵測到語音和 DTMF 輸入，系統會捨棄語音輸入，只考慮 DTMF 輸入。
如要啟用及自訂參數的 DTMF，請按照下列步驟操作：
控制台
- 如果尚未啟用虛擬服務專員語音和 IVR 設定，請啟用「Advanced settings」(進階設定)。
- 建立頁面參數。
- 在參數窗格中，將「Enable DTMF」(啟用 DTMF) 切換為開啟。
- 將「Max digits」(位數上限) 設為使用者可為這個參數提供的位數上限。
- 將「Finish digit」(結束數字) 設為撥號鍵盤值，用於終止參數的 DTMF 輸入。這項設定通常會使用
#。結束數字不會新增至代理上的 Dialogflow CX 查詢，因此如果結束數字是 #，而輸入內容是 123#，則實際查詢輸入內容會是「123」
建構代理時，您可以在模擬器中測試 DTMF 輸入。
流程範圍參數
流程範圍參數可定義為執行要求參數預設值或表單參數。只有在定義這些參數的流程處於啟用狀態時，才能參照這些參數，而且這些參數不會保留在工作階段參數中。
如要定義或參照流程範圍參數，請使用下列語法：
$flow.parameter-name
舉例來說，如果參數名稱是 date，您可以將參數定義或參照為 $flow.date。
請注意，定義參數時使用 $ 前置字元，與不使用 $ 定義參數的其他參數類型不同。
流程範圍參數定義範例：
流程範圍參數值的生命週期
雖然不常見，但在某些進階情況下，您可能需要瞭解流程範圍參數值在流程停用後，再次啟用時如何保留 (或捨棄)。
流程範圍參數值在流程停用後是否保留，取決於流程堆疊和堆疊上的流程執行個體。
- 當流程 A 使用特定轉移目標轉移至流程 B 時，流程 A (父項流程) 會保留在堆疊中，流程 A 會保留其流程範圍參數值，而流程 B (子項流程) 的新執行個體會新增至堆疊。
- 當子流程使用符號轉場目標 (例如 END_FLOW) 轉換回父流程時，子流程會從堆疊中移除，所有子流程範圍的參數值都會捨棄，而所有父流程範圍的參數值都會保留。
- 使用一系列具有特定轉換目標的轉換，流程堆疊可以包含一個流程類型的多個執行個體。每個流程類型執行個體都有專屬的流程範圍參數值。例如：A1 -> B1 -> C1 -> B2，其中 A、B 和 C 是流程類型，數字則代表這些流程類型的執行個體。在這個範例中，B1 和 B2 是流程 B 的不同執行個體，且具有專屬的流程範圍參數。
範例：
| 轉換 | 結果 |
|---|---|
| 流程 A (A1) 啟用。 流程 B (B1) 透過特定轉換目標啟用。 流程 B 使用符號轉場目標，轉換回啟動該流程的流程 A (A1)。 |
流程 A 會保留參數值。 |
| 流程 A (A1) 啟用。 流程 B (B1) 透過特定轉換目標啟用。 流程 B 使用特定轉換目標，轉換至流程 A (A2) 的新例項。 |
堆疊頂端流程 A (A2) 的新例項無法存取堆疊底部流程 A (A1) 的參數值。 |
| 流程 A (A1) 啟用。 流程 B (B1) 透過特定轉換目標啟用。 流程 A (A1) 使用符號轉換目標啟用。 流程 B (B2) 透過特定轉換目標啟用。 |
流程 B (B2) 不會保留第二次轉換 (B1) 後，在流程 B 啟用時設定的參數值。 |
要求範圍參數
要求範圍參數是由 Dialogflow CX 建立的短期參數，只能在目前要求的生命週期內參照，不會保留在工作階段參數中。
Dialogflow CX 會為下列功能產生要求範圍參數。
內建參數
您可以使用下列方法存取與要求相關聯的各種資料：
| 參考資料 | 說明 |
|---|---|
| $request.agent-id | 代理的 ID。 |
| $request.session-id | 工作階段 ID。 |
| $request.project-id | 專案 ID。 |
| $request.location-id | 代理位置的 ID。 |
| $request.language | QueryInput.language_code 中指定的語言代碼。 |
| $request.resolved-language | 代理在處理期間使用的實際語言代碼。解析後的語言可能與要求中指定的語言不同。舉例來說，如果代理僅支援「en」，而要求中指定的語言為「en-US」，則解析出的語言會是「en」。 |
| $request.user-utterance | 要求中指定的使用者目前語句。 |
| $request.last-agent-utterance | 代理最近傳送的話語。 |
| $request.nlu-confidence-score | 目前的 NLU 分類可信度分數。 |
| $request.end-user-metadata | 要求中指定的使用者中繼資料。 |
| $request.webhook_status_code | Webhook 呼叫的 HTTP 狀態碼。 |
自訂酬載
設定 QueryParameters.payload 後，您可以使用 $request.payload.param-id 存取對應的參數。
情緒分析
啟用情緒分析功能後，您可以使用下列情緒參考資料：
| 參考資料 | 類型 | 說明 |
|---|---|---|
| $request.sentiment.score | 數字 | 情緒分數介於 -1.0 (負面情緒) 和 1.0 (正面情緒) 之間。 |
| $request.sentiment.magnitude | 數字 | 表示情緒的整體強度 (包括正面和負面)，介於 0.0 和 +inf 之間。與分數不同，強度不會正規化；使用者輸入內容中的每種情緒表達 (包括正面和負面) 都會影響輸入內容的強度。輸入內容越長，強度可能越高。 |
| $request.sentiment.succeeded | 布林值 | 如果情緒分析成功，則為 True，否則為 False。 |
參數遮蓋
您可以為任何意圖或表單參數啟用參數遮蓋功能，這樣系統就會從記錄和 Dialogflow CX 內部儲存空間中，遮蓋使用者執行階段參數資料。遮蓋的參數在記錄中會顯示為 $parameter-name_redacted。
舉例來說，假設使用者輸入「我的地址是 1600 Amphitheatre Parkway」，系統會將 address 參數傳送至「1600 Amphitheatre Parkway」。記錄的文字會是「My address is $address_redacted」。
如要啟用參數遮蓋功能，請按照下列步驟操作：
控制台
建立或更新參數時，勾選「在記錄中遮蓋」核取方塊。
API
將 Intent 類型的 parameters[].redact 欄位設為 true。
選取意圖參照的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 意圖資源 | 意圖資源 |
| RPC | Intent 介面 | Intent 介面 |
| C++ | IntentsClient | 不適用 |
| C# | IntentsClient | 不適用 |
| Go | IntentsClient | 不適用 |
| Java | IntentsClient | IntentsClient |
| Node.js | IntentsClient | IntentsClient |
| PHP | 不適用 | 不適用 |
| Python | IntentsClient | IntentsClient |
| 小茹 | 不適用 | 不適用 |
將 Page 類型的 form.parameters[].redact 欄位設為 true。
選取頁面參考資料的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 網頁資源 | 網頁資源 |
| RPC | Page 介面 | Page 介面 |
| C++ | PagesClient | 不適用 |
| C# | PagesClient | 不適用 |
| Go | PagesClient | 不適用 |
| Java | PagesClient | PagesClient |
| Node.js | PagesClient | PagesClient |
| PHP | 不適用 | 不適用 |
| Python | PagesClient | PagesClient |
| 小茹 | 不適用 | 不適用 |
或者，您也可以遮蓋特定實體類型的所有參數。