使用變數

重要

在對生成式 AI 進行大量投資並增強 Microsoft Copilot 的整合後，Power Virtual Agents 的功能和特性現已成為 Microsoft Copilot Studio 的一部分。

當我們更新文件和培訓內容時，某些文章和螢幕擷取畫面可能會參考 Power Virtual Agents。

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

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

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

Web 應用程式

變數可存在於三個層級或範圍：

• 主題：變數只能用於其建立所在的主題中。 此範圍是您所建立變數的預設範圍。
• 全域變數在所有主題中都可以使用。 您可以變更任何主題變數的範圍，使之成為全域變數。
• 系統變數是與您的副手一起自動建立的。 這些變數提供更多關於交談或使用者的關聯式資訊。 在所有主題中都能使用。

變數類型

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

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

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

當您測試副手時，變數可能會暫時顯示為未知類型。 尚未指派值的未知變數。

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

實體

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

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

建立變數

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

挑選要使用的實體

預設會建立有多重選擇選項的問題節點。 若要使用其他預先建立實體或自訂實體，請選取識別方塊，然後選擇副手應偵聽的資訊類型。

重新命名變數

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

1. 選取變數，以在變數屬性窗格中將其開啟。

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

設定變數

您通常會使用問題節點，將使用者輸入儲存至變數。 不過，在某些情況下，您可能會想要自己來設定此值。 在這些情況下，請使用設定變數值節點。

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

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

   

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

   

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

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

使用常值

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

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

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

[變數] 窗格

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

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

變數屬性窗格

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

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

系統變數

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

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

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

姓名	類型​	已隱藏	定義
活動管道	選擇	可見	目前交談的管道識別碼
Activity.ChannelData	任何	隱藏	包含特定管道內容的物件
Activity.ChannelId	string	隱藏	目前交談的管道識別碼，其類型為字串
Activity.From.Id	string	隱藏	傳送者的管道特定唯一識別碼
Activity.From.Name	string	隱藏	傳送者的管道特定使用者易記名稱
Activity.Name	string	可見	事件的名稱
Activity.Text	string	可見	使用者傳送的最新訊息
Activity.Type	選擇	可見	活動的類型
活動 TypeId	string	隱藏	活動的類型，做為字串
Activity.Value	任何	隱藏	開放端點值
Bot.Name	string	可見	您副手的名稱
Channel.DisplayName	string	隱藏	管道的顯示名稱
Conversation.Id	string	可見	目前交談的唯一識別碼
LastActivity.Id	string	可見	先前所傳送活動的識別碼
LastMessage.Id	string	可見	使用者所傳送上一則訊息的識別碼
LastMessage.Text	string	可見	使用者傳送的上一則訊息
Recognizer.TriggerMessage.Id	string	可見	觸發目前主題之使用者訊息的識別碼
Recognizer.TriggerMessage.Text	string	可見	觸發目前主題的使用者訊息
User.DisplayName	string	可見	已登入使用者的顯示名稱

在主題之間傳遞變數

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

接收來自其他主題的值

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

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

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

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

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

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

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

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

設定目的地主題

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

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

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

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

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

   

5. 新增訊息節點。

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

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

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

9. 儲存主題。

設定來源主題

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

1. 移至來源主題。

2. 新增重新導向節點，並選取目的地主題。

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

   

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

   

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

   

5. 儲存主題。

將值傳回原始主題

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

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

設定傳回變數的來源主題

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

1. 移至來源主題。

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

3. 在識別下方，選取預建實體城市。

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

   

5. 儲存主題。

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

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

1. 移至目的地主題。

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

   

3. 儲存主題。

傳統

實體和變數類型

Copilot Studio 會使用實體，從使用者的回覆中找出特定類型的資訊。 變數類型在儲存時與已識別的資訊相關聯。 變數類型與實體類似。

每個實體或變數類型都會對應至基底類型，如下表所示。 當您使用對應的變數建立邏輯運算式時，基準類型會決定您可以使用的運算子。 它也會判斷是否可以將變數以輸入參數的方式饋送到流程或 Bot Framework 技能。

例如，布林值基底類型對應至運算子「等於」，可能的值為 True 或 False。 數字基底類型提供數字運算子，例如「等於」、「大於」或「大於或等於」等。

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

建立變數

在機器人製作畫布中，新增問題節點。 變數會自動建立在節點中。

1. 移至機器人的主題頁面，並打開您要新增變數的主題。

2. 選取新增節點 (+)，然後選取提出問題。

   

   會自動建立包含使用者回覆的變數。

   

挑選要使用的實體

根據預設，會建立有多個選項的問題節點。 若要使用不同的預建或自訂實體，請選擇要從節點進行識別的內容。

重新命名變數

自動建立的變數會以預設名稱提供。 若要重新命名變數，請選取變數名稱，輸入新名稱，然後選取完成。

在動作節點中使用變數

在動作節點中使用變數時，如果其基底類型符合您為流程或 Bot Framework 技能指定的參數類型相符，則可以將其提供給該參數。 動作節點的輸出會產生新的變數。

在動作節點中使用常值

您可以在動作節點的變數輸入欄位中輸入文字值，而不是從功能表中選取變數。

剖析值節點

剖析值節點可讓您將一種類型的值轉換成其他類型的值。 將節點新增至主題時，請選取 [新增節點 (+)]、[變數管理] 和 [剖析值]。

使用剖析值節點的主要案例主要是將原始 JSON 或非類型化變數 (在執行階段之前均未知其值或結構；例如 ChannelData) 轉換為具象類型。

程序會在呼叫流程時開始，然後流程再呼叫 API。 然後 API 會傳回結果。 通常，您可能必須剖析此回覆，並將一個或多個基本變數傳回 Copilot Studio。 使用剖析值節點，您可以將整個 API 結果做為字串傳送：

{
    "Name": "Gary",
    "Position": "PM",
    "Company": "Microsoft",
    "FormerPositions": [{
            "Position": "Engineer"
        }
    ]
}

您可以將現在使用的字串變數轉換為記錄變數，並在 Power Fx 中使用這個新節點來進行完整的 IntelliSense 支援。 使用範例資料的範例將有助於闡明此程序。

使用剖析值節點的範例

1. 新增剖析值節點，然後選取您要剖析的變數。

   

2. 選取資料類型。 在此案例中，請選擇「來自範例資料」。

   

3. 現在您可以按一下 [從範例 JSON 取得結構描述] 來提供 JSON。 按一下此處開啟編輯器，您可以在其中貼上範例。

   

4. 最後，指定要置入已剖析的值之變數。 通常，您會為此建立新的變數。

   

   請注意，輸出變數現在屬於正確類型 – 記錄。

   

現在您可以使用新變數。 在此處 Power Fx 編輯器中，您可以看到您已取得各種屬性的完整 IntelliSense。

除了剖析 JSON 字串之外，剖析值節點的金鑰使用將在執行階段時進行剖析 UntypedObjects。 其中最常見的是當您收到事件並且需要解析事件值時。 或者，您可能想要剖析 System.Activity.ChannelData 屬性，而此屬性在執行階段會依管道而有所不同。

在以下範例中，如果事件來自 Teams，則您需要使用 Teams 開發人員文件來尋找傳入事件外觀的範例，然後使用本節中所述的範例資料。

在主題之間傳遞變數

當重新導向至其他主題時，您可以將值傳遞至目的地主題中的變數，或是從中取得變數。 當您已經有主題所需的資訊時，在各主題之間傳遞變數就顯得非常有用。 您的使用者會很高興不必再次回答問題。 這在重構主題並將其分成可重複使用的元件，和想跨主題傳遞變數時也很實用。

Note

類型為 Custom Entity、Date and Time、Duration 和 Multiple-choice 的變數無法在主題之間傳遞。

接收來自其他主題的值

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

若要從其他主題接收值，請設定變數的屬性：

1. 在問題節點中，選取要從其他主題接收值的變數。

2. 在變數屬性窗格的主題 (有限範圍) 下，選取接收其他主題的值。

   

3. 儲存主題。

4. 移至要重新導向到的主題。 依照重新導向至其他主題中的步驟，重新導向至正確的主題。

5. 選取 + 為目的地主題新增輸入。

   

6. 從要將變數傳遞至的重新導向主題中，選取變數。

   

7. 在輸入或選取值下，在目前主題中選取要傳遞至重新導向主題的變數。

   

   變數會顯示在重新導向的節點中。

   

將值傳回原始主題

當主題提出問題 (或以其他方式從動作中取得變數) 時，可將此變數傳回已重新導向到它的原始主題。

在這種情況下，該變數也會變成原始主題的一部分，且可以做為任何其他變數使用。 這可協助您建構主題，讓機器人取得的資訊可在各主題間使用，減少對全域變數的需求。

若要將變數傳回至原始主題，請設定變數的屬性：

1. 在問題節點中，選取要從其他主題接收值的變數。

2. 在變數屬性窗格的主題 (有限範圍) 下，選取將變數傳回原始主題。

   

3. 儲存主題。

4. 移至要重新導向到的主題。 依照重新導向至其他主題中的步驟，重新導向至正確的主題。

   傳回主題的變數會顯示在重新導向主題中。 在主題中使用傳回的變數。

   

使用 [變數] 窗格

使用變數窗格一次選取多個變數的接收或傳回狀態。

1. 在主題的功能表列上，選取變數。

   

2. 對於主題中的每個變數，選取是否要在主題之間傳遞、接收 (或兩者) 值。

   

在變數輸入上使用常值

您可以將常值和變數傳遞至主題。 若要傳遞常值，請輸入要做為輸入的值，而不是選取變數。

相關主題

• 在主題間重複使用變數
• 自訂副手的外觀和風格