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