共用方式為


使用變數

您可以使用變數來儲存客戶的回覆,並在稍後的交談中重複使用其內容。

您也可以使用變數來建立邏輯運算式,將客戶動態傳遞至不同的交談路徑。 例如,將客戶的姓名保存在名為 UserName的變數中, 副駕駛可以在對話繼續時按姓名稱呼客戶。

變數也可以傳遞至其他主題Power Automate 流程,或從中傳回。

變數可以存在於四個層級或範圍:

  • 主題 變數只能在創建它們的主題中使用。 此範圍是您所建立變數的預設範圍。
  • 全域 變數 可用於所有主題。 您可以變更任何主題變數的範圍,使之成為全域變數。
  • 系統 變數 是使用 Copilot 自動創建的。 這些變數提供更多關於交談或使用者的關聯式資訊。 在所有主題中都能使用。
  • 環境 變數 在中創建 Power Platform ,並且是唯讀的 Copilot Studio。 環境變數儲存參數索引鍵和值,然後將其作為各種其他應用程式物件的輸入,包括 Copilot Studio。 將參數與取用物件分開可在同一環境中或將解決方案移轉到其他環境時變更值。 另一種選擇是將硬式編碼的參數值保留在使用它們的元件中。

變數類型

變數與基底類型相關聯。 類型決定變數可以包含哪些值,以及將其用於建構邏輯運算式時所能使用的運算子。

類型​ 描述
字串 用於表示文字的字元序列
布林值 只能是 truefalse 的邏輯值
數字 任何實數
資料表 值的清單,但是所有的值都必須是相同的類型
錄製 名稱/值組的集合,其中值可以是任何類型
日期時間 相對於某個時間點的日期、時間、星期幾或月份
選擇 具有關聯同義詞的字串值清單
Blank 「無值」或「未知值」的預留位置;如需詳細資訊,請參閱 Power Fx 中的空白

變數的類型是在第一次為其指派值時所設定。 在那之後,該變數的類型便已固定,無法為其指派任何其他類型的值。 例如,如果指定的起始值為 1 變數,則指派類型數字。 嘗試將其分配給 String"apples" 會導致錯誤。

在測試 Copilot 時,變數可能會暫時顯示為 unknown 類型未知 變數尚無值。

變數順序是由製作畫布由上至下的位置所決定。 也就是,將位於製作畫布頂端的節點視為在位於底端的節點之前。 使用條件節點建立分支時,分支是從左至右排序。 也就是,將最左側分支的節點視為在最右側分支的節點之前。

實體

Copilot Studio 會使用實體,從使用者的回覆中找出特定類型的資訊。 找出的資訊會儲存在類型適合該資訊的變數中。 下表列出了與預生成實體關聯的變數基類型。

Entity 可變基類型
多選選項 選擇
使用者的整個回覆 字串
年齡 數字
布林值 布林值
縣/市 字串
色彩 字串
洲別 字串
國家或地區 字串
日期和時間 日期時間
Email 字串
事件 字串
Integer Integer
語言 字串
Money 數字
數字 數字
序數 數字
組織 字串
百分比 數字
人員姓名 字串
電話號碼 字串
景點 字串
速度 數值
州/省 字串
街道地址 字串
溫度 數字
URL 字串
粗細 數字
郵遞區號 字串
自訂實體 選擇

建立變數

任何提示您選取變數做為輸出的節點 (例如問題節點) 會自動建立屬於適當類型的輸出變數。

問題節點的螢幕擷取畫面,其中反白顯示預設變數的名稱與類型。

提示

重新命名節點以使其更易於識別。 選擇節點的名稱欄位以直接更新名稱,或選擇節點的更多圖示 (...),並從功能表中選擇重新命名。 您還可以在代碼編輯器中 重新命名節點

無法重命名 發射鍵 nodes 和 Go to step 節點。

節點名稱的長度最多可達 500 個字元。

挑選要使用的實體

默認情況下,問題 節點是使用多選選項創建的。 若要使用其他預先建立實體或自訂實體,請選取識別方塊,然後選擇副手應偵聽的資訊類型。

Question 節點的屏幕截圖,其中“Choose information to identify”功能表打開,並突出顯示了“Person name”實體。

重新命名變數

建立變數時,系統會自動指派其名稱。 最佳做法是為您的變數提供有意義的名稱,以便讓必須維護副手的其他人清楚地了解其用途。

  1. 變數屬性窗格中選取變數以打開它。

  2. 變數名稱下方,輸入變數的新名稱。

設定變數

通常,您可以使用Question(問題 節點將使用者輸入保存到變數中。 但是,在某些情況下,您可能希望自己設置該值。 在這些情況下,請使用設定變數值節點。

  1. 選擇新增節點 (+) 以新增節點,然後選擇變數管理>設定變數值

  2. 選取設定變數底下的方塊,然後選取建立新變數

    [建立新變數] 按鈕的螢幕擷取畫面。

    新變數已建立。 在您將值指派給此變數之前,其類型為未知

    [變數值] 節點的螢幕擷取畫面,其中有類型未知的新變數 。

  3. 如果是到值,請使用以下選項之一指派值:

    • 輸入常值
    • 選取類型相同的現有變數。 此動作會將您的變數設定為與您所選變數相同的值。
    • 使用 Power Fx 公式。 Power Fx 公式對於無法使用常值的較複雜類型 (例如資料表和記錄類型) 很有用。

使用常值

您可以在任何變數中輸入常值,而不是選取變數值。

螢幕擷取畫面顯示名稱為 productName 的變數使用常值的情形。

螢幕擷取畫面顯示以常值做為重新導向節點中變數的輸入。

節點嘗試將常值解釋為字串、數字或布林值。 例如,123 會解譯為數字。 如果您要改以字串值來解譯,則可將值括在雙引號中,像這樣:"123"

在某些案例中,或使用更複雜的類型時,請使用 Power Fx 公式來設定特定類型。

[變數] 窗格

變數窗格可用來檢視主題中可用的所有變數,無論這些變數是在哪些節點中定義或使用。 對於每個變數,您都可以選擇讓變數從其他主題接收其值、將其值傳回給其他主題,還是兩者兼而有之。 您也可以選取變數以在變數屬性窗格中編輯其屬性。

若要開啟變數窗格,請選取主題的功能表列中的變數

Copilot Studio 製作畫布中 [變數] 窗格的螢幕擷取畫面,其中反白顯示 [變數] 按鈕。

變數屬性窗格

變數屬性窗格中,您可以重新命名變數、查看其使用所在位置,或將其轉換為全域變數。 不過,無法將其從全域變數轉換回主題變數。 您也可以選擇讓變數可以從其他主題接收值,還是將值傳遞給其他主題。

若要打開變數屬性窗格,請在變數窗格中選取一個變數。 您也可以選取任何節點中的變數來開啟變數屬性窗格。

[變數屬性] 窗格的螢幕擷取畫面。

環境變數

環境 變數 是一個 Power Platform 概念。 環境變數會啟用在 Power Platform 環境中移動應用程式的基本應用程式生命週期管理 (ALM) 案例。 在這個情境中,應用程式保持完全不變,只是來源環境和目標環境之間有一些關鍵的外部參考不同。

使用環境變數的方式與使用主題變數、全域變數和系統變數相同。 比較需要注意的區別是只能在唯讀模式下使用環境變數。 Copilot 作者無法修改 環境 變數。 Copilot Studio 但是,管理員可以在門戶中更改 環境 變數 Power Apps 的值。

將變數值設定為環境變數的「主題」頁面螢幕擷取畫面。

環境 Map to Copilot Studio 數據類型中的 Power Apps 變數類型,如下所示:

Copilot Studio 中的類型 輸入 Power Apps
十進位數 數字
JSON 從值中偵測類型。 如果不是 Json => 未指定 (驗證錯誤)
文字 string
是/否 布林值
資料來源 string
祕密 字串

注意

環境變數錯誤在測試聊天和發佈時可見。 但是,這些錯誤不會顯示在主題清單中,因為它們不是主題變數。

您無法在 Copilot Studio 中建立或編輯環境變數。 您必須使用 Power Apps 門戶更改或設置 環境 變數。 從 Copilot Studio 中,您可以使用變數窗格查看有關環境變數的資訊。 變數 窗格還具有原生創作體驗的連結。

使用 Azure Key Vault 密碼的環境變數

環境變數可以參考 Key Vault 中的祕密。 這是一種特殊的環境變數情況,具有獨特的考量。

若要在 Power Apps 門戶中創建機密 環境 變數,必須 配置其Key Vault

此外,您必須執行以下操作才能授權 Copilot Studio 讀取此 Key Vault:

  1. Key Vault Secrets User 角色指派給 Microsoft Virtual Agents Service 應用程式。

  2. 若要授權環境中的所有副手存取祕密,請在祕密上建立 AllowedEnvironments 標籤,並新增允許的環境識別碼 (以逗號分隔)。

  3. 若要僅授權環境中的特定副手使用此 Key Vault,請建立 AllowedCopilots 標籤,並將副手識別碼置於格式 {envId}/{schemaName} 中。 對於多個值,請用逗號分隔這些值。

如果您達到最大字元數,但仍需要新增更多副手,請新增另一個具有描述性但唯一名稱的標籤 (例如:AllowedCopilots2)。

祕密值在對話方塊執行階段快取五分鐘。 不成功的讀取會快取 30 秒。

警告

透過在副手中新增金鑰,您可以將此金鑰的值公開給可以在環境中編輯副手的所有使用者,因為這些使用者可以編輯副手,以傳回 SendMessage 節點中的值。

系統變數

每個副手都帶有內建的系統變數,可提供有關交談的其他資訊。

副手主題中系統變數的螢幕擷取畫面。

注意

有關支援語音副手變數的詳細資訊,請參閱使用語音變數

並非所有系統變數都會顯示在清單中。 您必須使用 Power Fx 公式來存取這些隱藏的系統變數。

若要在 Power Fx 公式中使用系統變數,您必須在變數名稱前加上 System.。 例如,若要在公式中包含系統變數 User.DisplayName,請將其稱為 System.User.DisplayName

姓名 類型​ 定義
Activity.Attachments 表格 使用者提供的檔案附件
Activity.Channel 選擇 目前交談的管道識別碼
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 表示副手在頻道內的顯示名稱。 在電話通道上下文中,此變數的值是 Copilot 附加到的電話號碼。
Activity.Text string 使用者傳送的最新訊息
Activity.Type 選擇 活動的類型
Activity.TypeId string 活動的類型,做為字串
Activity.Value 任何 開放端點值
Bot.EnvironmentId string 副手的環境識別碼
Bot.Id string 副手的識別碼
Bot.Name string 您副手的名稱
Bot.SchemaName string 副手的結構描述名稱
Bot.TenantId string 副手的租用戶識別碼
ClientPluginActions 選擇 要考慮用於生成動作的動態用戶端外掛程式動作的集合
Conversation.Id string 目前交談的唯一識別碼
Conversation.InTestMode 布林值 布林值旗標,表示交談是否發生在測試畫布中
Conversation.LocalTimeZone string 使用者要使用的時區名稱,採用 IANA 時區資料庫格式
Conversation.LocalTimeZoneOffset datetime 目前本地時區與 UTC 的時間偏移量
Error.Code string

目前錯誤的錯誤碼。

:僅當 發射鍵 受 On Error支援時,才支援此變數。

Error.Message 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 觸發目前主題之使用者訊息的識別碼
Recognizer.TriggeringMessage.Text string 觸發目前主題的使用者訊息
Recognizer.MultipleTopicsMatchedReason string

用於確定多個主題相符的原因。

:僅當 發射鍵 受 On Select Intent支援時,才支援此變數。

User.Language 選擇 此變數用於設定每個對話的使用者語言區域設定。
SignInReason 選擇

用於確定觸發主題時需要什麼登入選項。

:僅當 發射鍵 支援 On Sign In時,才支援此變數。

用於整合驗證的變數 (預設)

以下變數可用於配置為使用 Microsoft Entra ID身份驗證的 Copilot。 這是新 Copilot 的預設配置。

有關更多資訊,請參閱 身份驗證變數

姓名 類型​ 定義
User.DisplayName string 目前與副手對話的使用者的顯示名稱。
User.Email string 目前與副手對話的使用者的電子郵件地址。
User.FirstName string 目前與副手對話的使用者的名字。
User.Id string 目前與副手對話的使用者的唯一識別碼。
User.IsLoggedIn 布林值 布林值旗標,表示目前與副手對話的使用者是否已通過驗證。
User.LastName string 當前與 Copilot 通信的使用者的姓氏。
User.PrincipalName string 目前與副手對話的使用者的使用者主體名稱。

使用 Generic OAuth 2 進行手動身份驗證的變數

以下變數可用於配置為使用通用 OAuth 2 服務提供者的 Copilot。

姓名 類型​ 定義
User.AccessToken string 使用者與副手進行驗證的存取權杖。
User.DisplayName string 目前與副手對話的使用者的顯示名稱。
User.Id string 目前與副手對話的使用者的唯一識別碼。
User.IsLoggedIn 布林值 布林值旗標,表示目前與副手對話的使用者是否已通過驗證。

使用 Microsoft Entra ID 進行手動驗證的變數

以下變數可用於配置為使用ID(以前 Microsoft Entra )服務提供者的 Azure Active DirectoryCopilot。

姓名 類型​ 定義
User.AccessToken string 使用者與副手進行驗證的存取權杖。
User.DisplayName string 目前與副手對話的使用者的顯示名稱。
User.Email string 目前與副手對話的使用者的電子郵件地址。
User.FirstName string 目前與副手對話的使用者的名字。
User.Id string 目前與副手對話的使用者的唯一識別碼。
User.IsLoggedIn 布林值 布林值旗標,表示目前與副手對話的使用者是否已通過驗證。
User.LastName string 當前與 Copilot 通信的使用者的姓氏。
User.PrincipalName string 目前與副手對話的使用者的使用者主體名稱。

支援語音的副手的變數

以下變數僅可在支援語音的副手中使用。

注意

有關支援語音副手變數的詳細資訊,請參閱使用語音變數

姓名 類型​ 定義
Activity.InputDTMFKeys string 從電話接收的原始 DTMF 金鑰值。
Activity.SpeechRecognition.Confidence 數值 ASR 假設整個結果的信賴度分數,0 到 1。
Activity.SpeechRecognition.MinimallyFormattedText string ASR 假設結果的稍微格式化的文字。 例如,五百美元。 單字是拼寫的,但包括基本的大寫和標點符號。
Activity.UserInputType 選擇 終端使用者最近輸入的輸入類型。 該值可以是測試、語音或 DTMF。
Conversation.OnlyAllowDTMF 布林值 布林值旗標,表示 IVR 是否應在執行時設定為僅 DTMF 模式。
Conversation.SipUuiHeaderValue string UUI 標頭字串,用於在呼叫開始時將上下文傳遞到 IVR。

在主題之間傳遞變數

將主題重新導向至其他主題時,您可以在原始主題與目標主題之間傳遞變數的值。 當先前主題已收集到後來主題所需的資訊時,在主題之間傳遞變數特別有用。 使用者會很高興不必再次回答相同的問題。

接收來自其他主題的值

當主題定義變數 (例如,在問題節點) 時,副手會詢問使用者問題以填寫變數值。 如果副手已在先前的主題中取得該值,則無需再次提問。 在這些情況下,可以將此變數設定為接收其他主題的值。 將其他主題重新導向至此主題時,可以將變數的值 (或常值) 傳遞至此變數,並略過該問題。 使用者與副手交談時帶來完美的體驗。

在此範例中,我們使用兩個主題「問候」和「跟客戶談話」。 這兩個主題都要求提供客戶的姓名。 不過,如果「問候」主題先執行,則「跟客戶談話」主題會略過其問題。 反而改用從「問候」主題傳來的變數值。

以下是「跟客戶談話」主題的流程:

「跟客戶談話」主題交談流程的螢幕擷取畫面。

如「測試副手」窗格中所示,如果先觸發此主題,它會詢問使用者:「我應該怎麼稱呼您?」,然後將值儲存在名為 userName 的字串變數中。 userName 變數也會設定成從其他主題取得值。 此主題以訊息「希望您度過美好的一天,{userName}!」做為結尾

以下是「問候」主題的流程:

「問候」主題交談流程的螢幕擷取畫面。

如「測試副手」窗格中所示,如果先觸發此主題,它會詢問使用者:「您叫什麼名字?」,然後將值儲存在名為 UserName 的字串變數中。 主題會傳送訊息「很高興見到您,{UserName}!」,重新導向至「跟客戶談話」主題,這會傳送訊息「希望您度過美好的一天,{userName}!」請注意,「跟客戶談話」主題已略過再次詢問使用者姓名的步驟。 反而改用從「問候」主題傳來的 UserName 變數值。

最後,這裡又是那第二次交談,這次是從「跟客戶談話」主題的角度來看:

「跟客戶談話」主題交談流程在第一次觸發「問候」主題時的螢幕擷取畫面。

讓我們逐步解說設定要讓主題從其他主題接收值的步驟。 我們會使用目前的範例,只要主題需要取得先前主題中的值,同樣的步驟就會奏效。

設定目的地主題

目的地主題是要重新導向到的主題,此主題會接收來自其他主題的值。 在本範例中,這是「跟客戶談話」。

  1. 建立或移至目的地主題。

  2. 新增問題節點並輸入 What should I call you? 做為訊息。

  3. 識別下方,選取預建實體人員名稱

  4. 選取變數以開啟變數屬性窗格。 將其命名為 userName,然後選取從其他主題接收值

    「跟客戶談話」主題的螢幕擷取畫面,其中反白顯示 userName 變數及其屬性。

  5. 添加 Message 節點

  6. 在訊息方塊中,輸入 I hope you're having a wonderful day,

  7. 選取插入變數圖示 ({x}),然後選取 userName

  8. 選取變數後面的空白處,並鍵入 !

  9. 儲存主題。

設定來源主題

來源主題是執行重新導向的主題,此主題提供要傳遞給目的地主題的值。 在本範例中,這是「問候」。

  1. 移至來源主題。

  2. 添加 Redirect 節點 並選擇目標 主題。

  3. 選取 + 新增輸入,然後從要將值傳遞至的目的地主題中選取變數。

    「問候」主題的螢幕擷取畫面,其中重新導向節點已新增 userName 變數做為輸入。

  4. 選取 > 圖示,然後選取要傳遞其值的變數。

    「問候」主題的螢幕擷取畫面,其中已選取 UserName 變數。

    重新導向節點應該看起來像這樣:

    「問候」主題的螢幕擷取畫面,其中有已完成的重新導向節點。

  5. 儲存主題。

將值傳回原始主題

重新導向至某個主題,而此主題透過提出問題或其他方式取得變數時,可將此變數傳回至原始主題。 此變數會變成原始主題的一部分,並且可以像任何其他變數一樣使用。 因此,副手獲得的資訊可以跨主題使用,從而減少對全域變數的需求。

讓我們繼續上一節中的範例。 我們會在「跟客戶談話」主題中提出新問題,然後將解答傳回給「問候」主題。

設定傳回變數的來源主題

將變數傳回至主題時,來源主題是要重新導向到的主題,也就是提供傳遞回原始主題之值的主題。 在本範例中,這是「跟客戶談話」。

  1. 移至來源主題。

  2. 新增問題節點並輸入 What city do you live in? 做為訊息。

  3. 識別下方,選取預建實體城市

  4. 選取變數以開啟變數屬性窗格。 將其命名為 userCity,然後選取將值傳回原始主題

    「跟客戶談話」主題的螢幕擷取畫面,其中反白顯示 userCity 變數及其屬性。

  5. 儲存主題。

設定傳回變數的目的地主題

將變數傳回至主題時,目的地主題是進行重新導向的主題,也就是從其他主題接收值的主題。 在本範例中,這是「問候」。

  1. 移至目的地主題。

  2. 在來源主題中選取的變數會在重新導向節點中顯示為輸出變數。

    「問候」主題交談流程的螢幕擷取畫面,其中重新導向節點有傳回的變數。

  3. 儲存主題。