定義、參照、設定及取得參數
參數一般有四種用途：
- 在設計階段定義： 在設計階段，您可以使用主控台或 API 定義參數。 舉例來說，您可以定義意圖參數，並在訓練詞組中使用該參數，指出應擷取的使用者輸入內容。
- 設計階段參照： 參數參照是變數， 用於存放執行階段要擷取的參數值。 在設計階段，您可以使用控制台或 API，參照各種資料類型中的參數。舉例來說，您可以在路徑的靜態完成回應中參照工作階段參數。
- 在執行階段設定： 在執行階段，Conversational Agents (Dialogflow CX) 服務、呼叫 API 的服務和 Webhook 服務都可以設定參數值。 舉例來說，當使用者輸入內容與意圖相符，且輸入內容包含參數資料時，對話式代理程式 (Dialogflow CX) 服務會設定意圖參數的值。
- 在執行階段取得： 在執行階段，參數參照會包含已設定的參數值，您可以透過 API 或 Webhook 取得參數值。 舉例來說，如果系統比對的是意圖，並呼叫 Webhook，Webhook 服務就會收到意圖的參數值。
參數命名
參數命名須遵守下列規則：
- 使用下列字元：
[A-Z]、[a-z]、[0-9]、.、-、_ - 參數名稱不區分大小寫，因此 Conversational Agents (Dialogflow CX) 會將
Apple和apple視為相同參數。Webhook 和 API 用戶端程式碼也應將參數名稱視為不區分大小寫，因為 Conversational Agents (Dialogflow CX) 傳回的參數名稱不保證大小寫。 - 在不同意圖或表單中建立具有相同 ID 或顯示名稱的參數時，請確保所有定義的實體型別和其他設定都相同。如果實體類型或其他參數設定不同，請為每個定義使用不重複的參數 ID 或顯示名稱。
參數值類型
參數值支援多種值類型。 請參閱下方的工作階段部分，瞭解如何參照各參數值類型。mapTypeId 支援的類型如下：
| 類型 | 說明 |
|---|---|
| 純量 | 單一數字或字串值。 |
| 複合 | 透過比對複合實體或填寫意圖參數而填入的 JSON 物件，內含 original 和 resolved 欄位。 |
| 清單 | 為設定為清單的參數填入的純量或複合值清單。請參閱下列「Is List」選項。 |
參數空字串和空值
您可以將字串參數值設為 ""，將參數設為空字串。
您可以將任何參數值設為 null，表示該參數尚未設定。
參數原始值
當系統在執行階段將文字對應至特定實體時，通常會解析為更方便處理的值。例如，針對水果實體，系統可能會將使用者輸入的「apples」(蘋果) 這個字解析為「apple」。
只有工作階段參數參照的複合值類型可以參照原始值。
意圖參數
意圖會在比對出相符的意圖時，使用參數擷取使用者提供的資料。下列資料用於定義意圖參數：
- 「名稱」 (又稱「ID」或「顯示名稱」)：用於識別參數的名稱。
- 實體類型：與參數相關聯的實體類型。
- 「Is List」 (是清單)：如果為 true，系統會將參數視為值清單。
- 在記錄中遮蓋：如果為 true，系統會遮蓋使用者提供的參數資料。
定義意圖參數
建立意圖資料或為訓練詞組加註時，系統會在設計階段定義意圖參數。
參照意圖參數
意圖參數參照可用於意圖路徑的靜態執行要求回應訊息。
您可以參照原始值或已解析的值。
如要參照目前相符意圖的參數，請使用下列其中一種格式：
$intent.params.parameter-id.original $intent.params.parameter-id.resolved
舉例來說，如果參數 ID 為 date，則可使用 $intent.params.date.resolved 來參照已解析的值。
設定意圖參數
當使用者輸入內容在執行階段與意圖相符時，Conversational Agents (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 |
| Ruby | 不適用 | 不適用 |
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」區段標題，然後在參數表格中拖曳參數列。
如要刪除表單參數，請按一下頁面上的「參數」部分標題，將指標懸停在參數上，然後按一下「刪除」delete 按鈕。
參考表單參數
表單參數參照不會直接使用。 您只能查看個別表單參數或整個表單的填寫狀態。 您可以在條件條件路徑的條件規定中使用這些表單狀態參照。
如要檢查目前網頁是否已填寫完整表單，請使用下列條件：
$page.params.status = "FINAL"
如要檢查上一個回合是否填寫特定表單參數，請使用下列條件：
$page.params.parameter-id.status = "UPDATED"
設定表單參數
您可以透過多種方式設定表單參數值。 下列小節說明設定表單參數值的各項機制。
預設參數值
您可以為選填表單參數提供預設值。 表單填寫開始時，所有未設定的選用表單參數都會設為預設值。這些值可透過下列機制初始化或覆寫。
如果參數為必要參數，系統會忽略預設值。
填寫表單
Conversational Agents (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 |
| Ruby | 不適用 | 不適用 |
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，則可使用$session.params.location.zip-code參照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]參照第一個值。
設定工作階段參數
填寫完表單後，Conversational Agents (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 |
| Ruby | 不適用 | 不適用 |
取得工作階段參數
與 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 |
| Ruby | 不適用 | 不適用 |
Webhook 的接收工作階段參數值。
請參閱網路鉤子要求中的 sessionInfo.parameters 欄位。
參數傳播
當使用者輸入提供參數值時，參數可能會傳播至其他層級：
- 意圖比對設定意圖參數時，系統會將有效網頁的同名表單參數設為相同值。參數的實體類型是由意圖參數定義決定。
- 意圖比對設定意圖參數，或填寫表單時設定表單參數，這些參數都會成為工作階段參數。
電話整合的 DTMF
您可以為參數啟用及設定 DTMF (雙音多頻信號)。啟用後，使用電話語音整合的代理程式使用者，就能透過電話鍵盤提供參數值。
為減少模稜兩可的情況，DTMF 輸入內容可解讀為一般形式和 DTMF 專用形式 (建議)：
- 一般形式是使用者輸入的鍵盤值。
例如
123#。 - DTMF 專屬表單會將輸入內容轉換為
dtmf_digits_[digits]，其中[digits]是原始 DTMF 數字，*會替換為star，#會替換為pound。舉例來說，123#會解讀為dtmf_digits_123pound。
為參數比對實體型別時，Conversational Agents (Dialogflow CX) 會嘗試比對一般和 DTMF 專屬形式。如果實體類型用於 DTMF 輸入，建議您定義同義字 (例如 dtmf_digits_123)，以提升 NLU 比對效果。
如果 DTMF 輸入內容不符合終止條件 (未達到最大位數長度，或未以結束位數終止)，Conversational Agents (Dialogflow CX) 代理程式會持續等待更多輸入內容。在此期間，如果觸發無語音逾時，代理程式會改為叫用無輸入事件。如果只偵測到語音內容，代理程式會比對語音輸入內容。如果系統同時偵測到語音和 DTMF 輸入內容，則會捨棄語音輸入內容，只考量 DTMF 輸入內容。
如要為參數啟用及自訂 DTMF，請按照下列步驟操作：
主控台
- 如果尚未啟用「進階設定」，請從客服人員語音和 IVR 設定啟用。
- 建立網頁參數。
- 在參數窗格中，開啟「啟用 DTMF」。
- 將「Max digits」(最多位數) 設為使用者可為這個參數提供的最多位數。
- 將「結束數字」設為鍵盤值，以終止參數的 DTMF 輸入。
這項設定通常會使用
#。 系統不會將結束數字新增至服務專員的 Conversational Agents (Dialogflow CX) 查詢，因此如果結束數字為 #，且輸入內容為 123#，實際查詢輸入內容會是「123」
建構代理程式時，您可以在模擬工具中測試 DTMF 輸入內容。
智慧端點
如果代理程式已啟用智慧端點，您可以為數值參數自訂智慧端點行為。
- 將「Minimum digits」(最少位數) 設為提示智慧端點，等待收集所有數字。
- 設定「修正轉錄稿」，修正常見的數字轉錄錯誤，提升數字語音辨識準確度。只有指定 en 或 en-* 語言代碼的要求支援這項功能。
- 設定「等待逾時」，指定 Conversational Agents (Dialogflow CX) 等待使用者提供更多輸入內容的額外時間。
流程範圍參數
流程範圍參數可定義為預先設定的完成參數或表單參數。這些參數只能在定義流程處於啟用狀態時參照，且不會保留在工作階段參數中。
如要定義或參照流程範圍參數，請使用下列語法：
$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 使用符號轉場目標，轉場返回啟動流程 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) 後，於啟用期間設定的參數值。 |
要求範圍參數
要求範圍參數是由 Conversational Agents (Dialogflow CX) 建立的短期參數，只能在目前要求的生命週期內參照，且不會保留在工作階段參數中。
Conversational Agents (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 分類可信度分數。 |
自訂酬載
設定 QueryParameters.payload 後，您可以使用 $request.payload.param-id 存取對應的參數。
情緒分析
啟用情緒分析後，您可以使用下列情緒參照：
| 參考資料 | 類型 | 說明 |
|---|---|---|
| $request.sentiment.score | 數字 | 情緒分數介於 -1.0 (負面情緒) 和 1.0 (正面情緒) 之間。 |
| $request.sentiment.magnitude | 數字 | 表示整體情緒強度 (包括正面和負面)，介於 0.0 和 +inf 之間。與分數不同的是，幅度並無制式標準；只要使用者輸入內容出現情緒用字 (無論正負面) 都會提高輸入內容的幅度值。輸入內容越長，規模值可能就越大。 |
| $request.sentiment.succeeded | 布林值 | 如果情緒分析成功，則為 True，否則為 False。 |
參數遮蓋
您可以為任何意圖或表單參數啟用參數編輯功能，系統會從記錄和 Conversational Agents (Dialogflow CX) 內部儲存空間中，編輯使用者執行階段參數資料。記錄中會以 $parameter-name_redacted 顯示已遮蓋的參數。
舉例來說，假設使用者輸入「我的地址是 1600 Amphitheatre Parkway」，系統會將「1600 Amphitheatre Parkway」做為地址參數傳送。記錄的文字會是「My address is $address_redacted」。
如要啟用參數遮蓋功能，請按照下列步驟操作：
主控台
建立或更新參數時，勾選「在記錄中遮蓋」核取方塊。
API
將 Intent 類型的 parameters[].redact 欄位設為 true。
選取 Intent 參照的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 意圖資源 | 意圖資源 |
| RPC | 意圖介面 | 意圖介面 |
| C++ | IntentsClient | 不適用 |
| C# | IntentsClient | 不適用 |
| Go | IntentsClient | 不適用 |
| Java | IntentsClient | IntentsClient |
| Node.js | IntentsClient | IntentsClient |
| PHP | 不適用 | 不適用 |
| Python | IntentsClient | IntentsClient |
| Ruby | 不適用 | 不適用 |
將 Page 類型的 form.parameters[].redact 欄位設為 true。
選取頁面參照的通訊協定和版本：
| 通訊協定 | V3 | V3beta1 |
|---|---|---|
| REST | 網頁資源 | 網頁資源 |
| RPC | 頁面介面 | 頁面介面 |
| C++ | PagesClient | 不適用 |
| C# | PagesClient | 不適用 |
| Go | PagesClient | 不適用 |
| Java | PagesClient | PagesClient |
| Node.js | PagesClient | PagesClient |
| PHP | 不適用 | 不適用 |
| Python | PagesClient | PagesClient |
| Ruby | 不適用 | 不適用 |
或者，您也可以遮蓋特定實體類型的所有參數。