變數概述
變數可以存在於四個層級或範圍：
- 主題變數只能在建立它們的主題中使用。 此範圍是您所建立變數的預設範圍。
- 全域變數可以在所有主題中使用。 您可以變更任何主題變數的範圍，使之成為全域變數。
- 系統變數是由您的代理程式自動建立的。 這些變數提供更多關於交談或使用者的關聯式資訊。 在所有主題中都能使用。
- 環境變數是在 Power Platform 中建立，並在 Copilot Studio 中為唯讀。 環境變數儲存參數索引鍵和值，然後將其作為各種其他應用程式物件的輸入，包括 Copilot Studio。 將參數與取用物件分開可在同一環境中或將解決方案移轉到其他環境時變更值。 另一種選擇是將硬式編碼的參數值保留在使用它們的元件中。
變數類型
變數與基底類型相關聯。 類型決定變數可以包含哪些值，以及將其用於建構邏輯運算式時所能使用的運算子。
| 類型 | 描述 |
|---|---|
| 字串 | 用於表示文字的字元序列 |
| 布林值 | 只能是 true 或 false 的邏輯值 |
| 數字 | 任何實數 |
| 資料表 | 值的清單，但是所有的值都必須是相同的類型 |
| 錄製 | 名稱/值組的集合，其中值可以是任何類型 |
| 日期時間 | 相對於某個時間點的日期、時間、星期幾或月份 |
| 選擇 | 具有關聯同義詞的字串值清單 |
| Blank | 「無值」或「未知值」的預留位置；如需詳細資訊，請參閱 Power Fx 中的空白 |
變數的類型是在第一次為其指派值時所設定。 在那之後，該變數的類型便已固定，無法為其指派任何其他類型的值。 例如，如果指定的起始值為 1 變數，則指派類型數字。 嘗試將其指派給 "apples" 的 字串值會導致錯誤。
當您測試代理程式時，變數可能會暫時顯示為未知類型。 尚未指派值的未知變數。
變數順序是由製作畫布由上至下的位置所決定。 製作畫布頂部的節點優先於底部的節點。
使用條件節點建立分支時，分支是從左至右排序。 最左邊分支的節點在最右邊分支的節點之前被考慮。
實體
Copilot Studio 會使用實體，從使用者的回覆中找出特定類型的資訊。 找出的資訊會儲存在類型適合該資訊的變數中。 下表列出了與預先建構實體關聯的變數基本類型。
| Entity | 變數基底類型 |
|---|---|
| 多選選項 | 選擇 |
| 使用者的整個回覆 | 字串 |
| 年齡 | 數字 |
| 布林值 | 布林值 |
| 縣/市 | 字串 |
| 色彩 | 字串 |
| 洲別 | 字串 |
| 國家或地區 | 字串 |
| 日期和時間 | 日期時間 |
| 字串 | |
| 事件 | 字串 |
| Integer | Integer |
| 語言 | 字串 |
| Money | 數字 |
| 數字 | 數字 |
| 序數 | 數字 |
| 組織 | 字串 |
| 百分比 | 數字 |
| 人員姓名 | 字串 |
| 電話號碼 | 字串 |
| 景點 | 字串 |
| 速度 | 數值 |
| 州/省 | 字串 |
| 街道地址 | 字串 |
| 溫度 | 數字 |
| URL | 字串 |
| 粗細 | 數字 |
| 郵遞區號 | 字串 |
| 自訂實體 | 選擇 |
環境變數
環境變數是一個 Power Platform 概念。 環境變數會啟用在 Power Platform 環境中移動應用程式的基本應用程式生命週期管理 (ALM) 案例。 在這個情境中，應用程式保持完全不變，只是來源環境和目標環境之間有一些關鍵的外部參考不同。
使用環境變數的方式與主題、全域和系統變數相同。 一個顯著的差異是環境變數在 Copilot Studio 中是唯讀的。 代理程式作者無法修改 Copilot Studio 中的環境變數。 但是，管理員可以變更 Power Apps 中環境變數的值。 在 Copilot Studio 中，您可以使用變數面板來查看有關環境變數的資訊。 變數面板還具有指向本機製作體驗的連結。
使用環境變數的代理程式的已發佈版本，具有在發佈代理程式時為這些變數設定的值。 每當管理員更新環境變數時，您都必須重新發佈使用這些變數的任何代理程式，以使變更在執行階段生效。 但是，有一個例外：當密碼類型的環境變數值發生變更時，您不需要重新發佈代理程式。 與其他環境變數不同，秘密變數是在執行階段擷取的。
Copilot Studio 中的環境變數類型對應到 Power Apps 資料類型，如下所示：
| Copilot Studio 中的類型 | Power Apps 中的類型 |
|---|---|
| 十進位數 | 數字 |
| JSON | 從值中偵測類型。 如果不是 JSON => 未指定 (驗證錯誤) |
| 文字 | 字串 |
| 是/否 | 布林值 |
| 資料來源 | 字串 |
| 祕密 | 字串 |
注意
環境變數錯誤在測試聊天和發佈時可見。 但是，這些錯誤不會顯示在主題清單中，因為它們不是主題變數。
系統變數
每個代理程式都帶有內建系統變數，可提供有關交談的附加資訊。
注意
有關支援語音的代理程式變數的更多資訊，請參閱使用語音變數。
並非所有系統變數都會顯示在清單中。 您必須使用 Power Fx 公式來存取這些隱藏的系統變數。
若要在 Power Fx 公式中使用系統變數，您必須在變數名稱前加上 System.。 例如，若要在公式中包含系統變數 User.DisplayName，請將其稱為 System.User.DisplayName。
| 姓名 | 類型 | 定義 |
|---|---|---|
| Activity.Attachments | 表格 | 使用者提供的檔案附件 |
| 活動管道 | 選擇 | 目前交談的管道識別碼 |
| Activity.ChannelData | 任何 | 包含特定管道內容的物件 |
| Activity.ChannelId | string | 目前交談的管道識別碼，其類型為字串 |
| Activity.From.Id | string | 傳送者的管道特定唯一識別碼 |
| Activity.From.Name | string | 傳送者的管道特定使用者易記名稱 |
| Activity.Name | string | 事件的名稱 |
| Activity.Recipient.Id | string | 傳入活動的 Type 屬性。 |
| Activity.Recipient.Name | string | 表示代理程式在頻道內的顯示名稱。 在電話通道上下文中，此變數的值是代理程式所連接的電話號碼。 |
| Activity.Text | string | 使用者傳送的最新訊息 |
| Activity.Type | 選擇 | 活動的類型 |
| 活動 TypeId | string | 活動的類型，做為字串 |
| Activity.Value | 任何 | 開放端點值 |
| Bot.EnvironmentId | string | 代理程式的環境ID |
| Bot.Id | string | 代理程式ID |
| Bot.Name | string | 您的代理程式的名稱 |
| Bot.SchemaName | string | 代理程式的架構名稱 |
| Bot.TenantId | string | 代理程式的租用戶 ID |
| ClientPluginActions | 選擇 | 用於生成式協調流程時考慮的動態用戶端外掛程式操作的集合 |
| Conversation.Id | string | 目前交談的唯一識別碼 |
| Conversation.InTestMode | 布林值 | 布林值旗標，表示交談是否發生在測試畫布中 |
| Conversation.LocalTimeZone | string | 使用者要使用的時區名稱，採用 IANA 時區資料庫格式 |
| Conversation.LocalTimeZoneOffset | datetime | 目前本地時區與 UTC 的時間偏移量 |
| Error.Code | string | 目前錯誤的錯誤碼。 目前錯誤的錯誤訊息。 |
| 錯誤訊息 | string | 目前錯誤的錯誤訊息。 注意：僅當觸發程序為 On Error 時才支援此變數。 |
| FallbackCount | 數值 | 此變數會計算主題無法與使用者輸入相符的次數。 注意：僅當觸發程序為 On Unknown Intent 時才支援此變數。 |
| InactivityTimer.Continue | 布林值 | 布林值旗標，表示計時器是否需要繼續。 注意：僅當觸發程序為 Inactivity 時才支援此變數。 |
| InactivityTimer.Count | 數值 | 在設定時間後，由於使用者處於非活動狀態而觸發 OnInactivity 計時器的次數。 注意：僅當觸發程序為 Inactivity 時才支援此變數。 |
| LastMessage.Id | string | 使用者所傳送上一則訊息的識別碼 |
| LastMessage.Text | string | 使用者傳送的上一則訊息 |
| Recognizer.ExtractedEntities | 選擇 | 表示從觸發訊息中提取的實體。 注意：僅當觸發程序為 On Select Intent 時才支援此變數。 |
| Recognizer.IntentOptions | 選擇 | 表示識別器傳回不明確結果時的意圖選項。 注意：僅當觸發程序為 On Select Intent 時才支援此變數。 |
| Recognizer.SelectedIntent | 選擇 | 表示從識別器中選擇的意圖。 注意：僅當觸發程序為 On Select Intent 時才支援此變數。 |
| Recognizer.TriggeringMessage.Id | string | 觸發目前主題之使用者訊息的識別碼 |
| 識別器.觸發訊息.文字 | string | 觸發目前主題的使用者訊息 |
| Recognizer.MultipleTopicsMatchedReason | string | 用於確定多個主題匹配的原因。 注意：僅當觸發程序為 On Select Intent 時才支援此變數。 |
| SignInReason | 選擇 | 用於確定觸發主題時需要什麼登入選項。 注意：僅當觸發程序為 On Sign In 時才支援此變數。 |
| User.Language | 選擇 | 此變數用於設定每個對話的使用者語言區域設定。 |
用於整合驗證的變數 (預設)
以下變數可用於設定為透過 Microsoft 進行驗證的代理程式。 此設定使用 Microsoft Entra ID 驗證，並且是新代理程式的預設設定。
有關詳細資訊，請參閱驗證變數。
| 姓名 | 類型 | 定義 |
|---|---|---|
| User.DisplayName | string | 目前與代理程式交談的使用者的顯示名稱。 |
| User.Email | string | 目前與代理程式交談的使用者的電子郵件地址。 |
| User.FirstName | string | 目前與代理程式交談的使用者的名字。 |
| User.Id | string | 目前與代理程式交談的使用者的唯一 ID。 |
| User.IsLoggedIn | 布林值 | 布爾標誌，表示目前與代理程式交談的使用者是否經過驗證。 |
| User.LastName | string | 目前與代理程式交談的使用者的姓氏。 |
| User.PrincipalName | string | 目前與代理程式交談的使用者的使用者主體名稱。 |
使用通用 OAuth 2 進行手動驗證的變數
以下變數可用於設定為使用通用 OAuth 2 服務提供者的代理程式。
| 姓名 | 類型 | 定義 |
|---|---|---|
| User.AccessToken | string | 使用者透過代理程式進行驗證的存取權杖。 |
| User.DisplayName | string | 目前與代理程式交談的使用者的顯示名稱。 |
| User.Id | string | 目前與代理程式交談的使用者的唯一 ID。 |
| User.IsLoggedIn | 布林值 | 布爾標誌，表示目前與代理程式交談的使用者是否經過驗證。 |
使用 Microsoft Entra ID 進行手動驗證的變數
以下變數可用於設定為使用 Microsoft Entra ID (以前稱為 Azure Active Directory) 服務提供者的代理程式。
| 姓名 | 類型 | 定義 |
|---|---|---|
| User.AccessToken | string | 使用者透過代理程式進行驗證的存取權杖。 |
| User.DisplayName | string | 目前與代理程式交談的使用者的顯示名稱。 |
| User.Email | string | 目前與代理程式交談的使用者的電子郵件地址。 |
| User.FirstName | string | 目前與代理程式交談的使用者的名字。 |
| User.Id | string | 目前與代理程式交談的使用者的唯一 ID。 |
| User.IsLoggedIn | 布林值 | 布爾標誌，表示目前與代理程式交談的使用者是否經過驗證。 |
| User.LastName | string | 目前與代理程式交談的使用者的姓氏。 |
| User.PrincipalName | string | 目前與代理程式交談的使用者的主體名稱。 |
支援語音的代理程式的變數
以下變數僅適用於啟用語音的代理程式。
注意
有關支援語音的代理程式變數的更多資訊，請參閱使用語音變數。
| 姓名 | 類型 | 定義 |
|---|---|---|
| Activity.InputDTMFKeys | string | 從電話接收的原始 DTMF 金鑰值。 |
| Activity.SpeechRecognition.Confidence | 數值 | Azure Site Recovery 假設整個結果的信心分數為 0 到 1。 |
| Activity.SpeechRecognition.MinimallyFormattedText | string | Azure Site Recovery 假設結果的稍微格式化的文字。 例如，「五百美元」。 單字是拼寫的，但包括基本的大寫和標點符號。 |
| Activity.UserInputType | 選擇 | 使用者最近輸入的輸入類型。 該值可以是測試、語音或 DTMF。 |
| Conversation.OnlyAllowDTMF | 布林值 | 布林值旗標，表示 IVR 是否應在執行時設定為僅 DTMF 模式。 |
| Conversation.SipUuiHeaderValue | string | UUI 標頭字串，用於在呼叫開始時將上下文傳遞到 IVR。 |