使用變數

發行項
01/08/2025

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

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

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

建立變數

Web 應用程式
傳統

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

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

提示

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

無法重新命名觸發程序節點和前往步驟節點。

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

預設情況下，問題節點是使用多項選擇選項建立的。若要使用不同的預先建置或自訂實體，請選擇識別方塊，然後選擇代理程式應偵聽的資訊類型。

「選擇要識別的資訊」面板開啟的問題節點的螢幕擷取畫面。

重新命名變數

Web 應用程式
傳統

建立變數時，系統會自動指派其名稱。最佳做法是為您的變數提供有意義的名稱，以使必須維護您的代理程式的其他任何人都清楚其目的。

在變數屬性窗格中選取變數以打開它。
在變數名稱下方，輸入變數的新名稱。

設定變數

通常，您會使用問題節點將使用者輸入儲存在變數中。然而，在某些情況下您可能想要自行設定變數的值。在這些情況下，請使用設定變數值節點。

選擇新增節點 (+) 以新增節點，然後選擇變數管理>設定變數值。
選取設定變數底下的方塊，然後選取建立新變數。

新變數已建立。在您將值指派給此變數之前，其類型為未知。
如果是到值，請使用以下選項之一指派值：
- 輸入常值。
- 選取類型相同的現有變數。此動作會將您的變數設定為與您所選變數相同的值。
- 使用 Power Fx 公式。 Power Fx 公式對於無法使用常值的較複雜類型 (例如資料表和記錄類型) 很有用。

注意

設定字串類型變數時，如果遇到設定變數和目標值不匹配，則會出現錯誤訊息和修復類型不匹配按鈕。選擇該按鈕可讓 Copilot Studio 自動產生 Power Fx 公式，解決不相符問題。

在動作節點中使用變數

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

帶有技能動作的輸入和輸出參數動作節點的螢幕擷取畫面。

使用變數輸入的常值

在可以為輸入參數設定值的節點中，您始終可以輸入常值，而不是選擇另一個變數作為值。

使用名為 productName 的變數輸入參數的常值的螢幕擷取畫面。

節點嘗試將常值解釋為字串、數字或布林值。例如，123 會解釋為數字。如果您希望將其解釋為字串值，則可以將該值括在雙引號中，如下所示："123"。

對於某些情境 (例如，使用複雜類型的情境)，您可能需要使用 Power Fx 公式來設定特定類型。

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

環境變數可以參考 Key Vault 中的祕密。秘密環境變數是具有獨特考慮因素的環境變數的特殊情況。

若要在 Power Apps 入口網站中建立祕密環境變數，必須設定其 Key Vault。

若要授權 Copilot Studio 讀取此 Key Vault，您必須執行以下動作：

將 Key Vault Secrets User 角色指派給 Microsoft Virtual Agents Service 應用程式。
若要授權環境中的所有代理程式存取該金鑰，請在該金鑰上建立一個標籤 AllowedEnvironments 並新增以逗號分隔的允許的環境 ID。
若要僅授權環境中的特定代理程式使用此金鑰保存庫，請建立標籤 AllowedAgents 並以 {envId}/{schemaName} 格式放置代理程式識別碼。對於多個值，請用逗號分隔這些值。

如果達到最大字元數但仍需要新增更多代理程式，請新增另一個具有描述性但唯一名稱的標籤 (例如：AllowedAgents2)。

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

警告

透過在代理程式中新增機密，您可以將此機密的值公開給可以在環境中編輯代理程式的所有使用者，因為這些使用者可以編輯代理程式以傳回 SendMessage 節點中的值。

[變數] 窗格

Web 應用程式
傳統

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

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

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

變數屬性窗格

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

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

在主題之間傳遞變數

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

接收來自其他主題的值

當主題定義變數時 (例如，在問題節點中)，代理程式會向使用者詢問問題以填入變數的值。如果代理程式已經獲得了先前主題中的值，則沒有理由再次詢問該問題。在這些情況下，可以將此變數設定為接收其他主題的值。當另一個主題重新導向到此主題時，它可以將變數的值或常值傳遞給該變數，並跳過該問題。使用者與代理程式交談的體驗是無縫的。

Web 應用程式
傳統

在此範例中，我們使用兩個主題：問候和與客戶交談。這兩個主題都要求提供客戶的姓名。但是，如果先執行問候主題，則與客戶交談主題會跳過其問題。相反，它使用從問候主題傳遞的變數值。

以下是與客戶交談主題的流程：

如測試面板所示，如果首先觸發該主題，它會詢問使用者「我應該打電話給您嗎？」它將值儲存在名為 customerName 的字串變數中。 customerName 變數也設定為從其他主題取得其值。這個主題以以下訊息結束：「祝您度過愉快的一天，customerName！」

以下是問候主題的流程：

如測試面板所示，如果首先觸發該主題，它會詢問使用者「您叫什麼名字？」它將值儲存在名為 customerName 的字串變數中。該主題傳送訊息「很高興見到您，customerName！」然後，它會重新導向到與客戶交談主題，該主題傳送訊息「祝您度過愉快的一天，customerName！」但請注意，與客戶交談主題跳過了再次詢問使用者名稱的過程。相反，它使用從問候主題傳遞的 customerName 變數的值。

最後，這是第二次交談，這次是從與客戶交談主題的角度來看的：

讓我們逐步解說設定要讓主題從其他主題接收值的步驟。我們的範例情境使用預先定義主題問候作為來源主題，使用新主題與客戶交談作為目標主題，但相同的步驟適用於應盡可能使用早期主題中的值的任何主題。

設定目的地主題

目的地主題是要重新導向到的主題，此主題會接收來自其他主題的值。在我們的範例中，這是與客戶交談。

建立一個新主題並將其命名為「與客戶交談」。
新增觸發字詞，例如「跟我說話」、「與我說話」、「與我聊天」。
新增問題節點並輸入「我應該打電話給您嗎？」的訊息。
在識別下方，選取預建實體人員名稱。
選擇變數的名稱。這將打開變數屬性面板。
將預設名稱替換為「customerName」，然後選擇從其他主題接收值。
新增訊息節點。
在訊息框中輸入「我希望您今天過得愉快」。
選擇插入變數圖示 ({x})，然後選擇 customerName。
選擇變數後面的空格並輸入「!」。
儲存主題。

設定來源主題

來源主題是進行重新導向的主題，即提供值並將其傳遞到目標主題的主題。在我們的範例中，這是問候。

前往問候主題並刪除除觸發程序節點之外的預設節點。
新增問題節點並輸入「您叫什麼名字？」的訊息。
在識別下方，選取預建實體人員名稱。
將預設名稱替換為「customerNameFromGreeting」。
新增訊息節點。
在訊息框中輸入「很高興見到您」。
選擇插入變數圖示 ({x})，然後選擇 customerNameFromGreeting。
選擇變數後面的空格並輸入「!」。
新增重新導向節點，然後選擇目標主題與客戶交談。
選擇新增輸入，然後從要將值傳遞至的目的地主題中選取變數。
選擇 > 圖示，然後選擇要傳遞其值的變數，在此範例中為 customerNameFromGreeting。

重新導向節點應該看起來像這樣：
儲存主題。

將值傳回原始主題

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

Web 應用程式
傳統

讓我們繼續上一節中的範例。我們在與客戶交談主題中提出一個新問題，然後將答案回到問候主題。

設定傳回變數的來源主題

當您將變數返回主題時，來源主題是提供要傳回原始主題的值的主題。在此範例中，來源主題是與客戶交談。

移至來源主題。
新增問題節點並輸入「您住在哪個城市？」的訊息。
在識別下方，選取預建實體城市。
選取變數以開啟變數屬性窗格。將其命名為「customerCity」，然後選擇將值傳回原始主題。
新增訊息節點。
選擇插入變數圖示 ({x})，然後選擇 customerCity。
在訊息框中的變數後面輸入「一年中的這個時候一定很漂亮！」。
儲存主題。

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

當您將變數返回主題時，目標主題是從目前主題接收值的主題。在我們的範例中，目標主題是問候。

移至目的地主題。
您在來源主題中選擇的變數應作為輸出變數出現在重新導向節點上。
儲存主題。

剖析值節點

剖析值節點可讓您將一種類型的值轉換為其他類型的值。在主題中新增節點時，選擇新增節點圖示，指向變數管理，然後選擇剖析值。

新增節點的功能表螢幕擷取畫面，選擇「變數管理」，然後選擇「剖析值」。

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

程序會在呼叫流程時開始，然後流程再呼叫 API。然後 API 會傳回結果。通常，您需要剖析此回應並傳回一個或多個原始變數。使用剖析值節點，您可以將整個 API 結果做為字串傳送。例如:

{
    "Name": "Parker",
    "Position": "Product manager",
    "Company": "Contoso",
    "FormerPositions": [{
            "Position": "Customer service representative"
        }
    ]
}

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

使用剖析值節點的範例

新增剖析值節點，然後選取您要剖析的變數。
選取資料類型。在本例中，選擇來自範例資料。
選擇從範例 JSON 取得結構描述，然後在開啟的編輯器中輸入所需的 JSON 範例。
最後，指定要置入已剖析的值之變數。通常，您會為此建立新的變數。

請注意，輸出變數現在具有正確的類型：記錄。

除了剖析 JSON 字串之外，剖析值節點的一個重要用途是在執行階段剖析 UntypedObjects。最常見的使用案例是當您收到事件並且需要剖析事件值時。或者您可能想要剖析 System.Activity.ChannelData 屬性，該屬性在執行階段因通道而異。

如果要剖析來自 Teams 的事件的資訊，則需要使用 Teams 開發人員文件來查找預期事件的範例，然後使用此範例作為範例資料，如本節前面所述。

共用方式為