使用变量

重要提示

继在生成式人工智能的重大投资和跨 Microsoft Copilot 的增强集成之后，Power Virtual Agents 功能和特性现已成为 Microsoft Copilot Studio 的一部分。

在我们更新文档和培训内容时，一些文章和截图可能会参考 Power Virtual Agents。

您可以使用变量来保存客户的回答，并在稍后的对话中重复使用他们的内容。

还可以使用变量创建逻辑表达式以沿着不同对话路径动态传递客户。 例如，将客户的姓名保存在名为 UserName 的变量中，助手可以在对话继续时按姓名处理该客户。

变量也可以传递到其他主题和Power Automate 流并从其中返回。

Web 应用程序

变量可以存在于以下三个级别或范围：

• 主题变量只能在创建变量所在的主题中使用。 此范围是您创建的变量的默认范围。
• 全局 变量可用于所有主题。 您可以更改主题变量的范围以使主题变量成为全局变量。
• 系统变量是使用助手自动创建的。 它们提供有关对话或用户的更多上下文信息。 它们可用于所有主题。

变量类型

变量与基本类型关联。 类型决定了变量可以包含哪些值，以及在使用变量构造逻辑表达式时可以使用的运算符。

类型​​	说明
String	用于表示文本的一系列字符
布尔型	只能为 true 或 false 的逻辑值
数字	任何实数
表	值列表，但所有值必须是相同类型
记录	名称-值对（其中的值可以是任意类型）的集合
日期/时间	与时间点相关的日期、时间、周中某一天或月份
单选	具有关联同义词的字符串值的列表
空白	“无值”或“未知值”的占位符；有关详细信息，请参阅 Power Fx 中的空白

变量的类型是在首次为变量分配值时设置的。 此后，该变量的类型是固定的，它不能被赋予任何其他类型的值。 例如，给定起始值为 1 的变量会被分配数字类型。 尝试将其分配给字符串值 "apples" 将导致错误。

测试助手时，变量可能会暂时显示为未知类型。 尚未为未知变量分配值。

变量的顺序从创作画布的顶部向底部确定。 即，在底部节点之前先考虑创作画布顶部的节点。 当创建包含条件节点的分支时，分支按从左到右的顺序排序。 即，先考虑最左侧分支中的节点，然后考虑最右侧分支中的节点。

实体

Microsoft Copilot Studio 使用实体从用户的回复中识别特定类型的信息。 标识的信息保存在适合该信息的类型变量中。 下表列出了与预建实体相关联的变量基类型。

Entity	变量的基类型
多选选项	单选
用户的完整响应	String
年限	数字
布尔型	布尔型
City	String
Color	String
洲	String
国家或地区	String
日期和时间	日期/时间
Email	String
活动	String
整型	整型
语言	String
金钱	数字
数字	数字
顺序	数字
组织	String
百分比	数字
人员姓名	String
电话号码	String
兴趣点	String
速度	数
州	String
街道地址	String
温度	数字
URL	String
粗细	数字
邮政编码	String
自定义实体	单选

创建变量

提示您选择变量作为输出的任何节点，例如问题节点，都会自动创建一个合适类型的输出变量。

选取要使用的实体

默认情况下，将创建具有多选选项的问题节点。 若要使用不同的预建实体或自定义实体，请选择标识框，然后选择助手应侦听的信息类型。

重命名变量

创建变量时会自动为变量分配一个名称。 最佳做法是为您的变量提供有意义的名称，以使必须维护您的助手的其他任何人都清楚它们的用途。

1. 选择变量以在变量属性窗格中将其打开。

2. 在变量名称下面，请为变量输入新名称。

设置变量

通常您将使用问题节点将用户输入保存到变量中。 不过，在某些情况下，您可能想要自己设置值。 在这种情况下，请使用设置变量值节点。

1. 选择添加节点 (+) 以添加节点，然后选择设置变量值。

2. 选中设置变量下面的方框，然后选择创建新变量。

   

   创建了新变量。 在为其赋值之前，其类型是未知。

   

3. 对于目标值，使用以下选项之一分配一个值：

   • 键入文字值。
   • 选择同一类型的现有变量。 此操作会将您的变量设置为与您选择的变量相同的值。
   • 使用 Power Fx 公式。 Power Fx 公式对于不能使用文字值的更复杂类型很有用，例如表和记录类型。

使用文字值

您可以将文字值输入到任何变量中，而不是选择变量值。

该节点会尝试将文字值解释为字符串、数字或布尔类型。 例如，123 将被解释为一个数字。 如果您希望将其解释为字符串值，您可以用双引号括住此值，如下所示："123"。

对于某些情况下，或者如果您使用更复杂的类型，请使用 Power Fx 公式来设置特定类型。

变量窗格

变量窗格是您可以查看主题中可用的所有变量的地方，无论它们是在哪些节点中定义或使用的。 对于每个变量，您可以选择它是可以从其他主题接收其值、将其值返回给其他主题，还是两者均可。 您还可以在变量属性窗格中选择一个变量来编辑其属性。

要打开变量窗格，请在主题的菜单栏中选择变量。

变量属性窗格

在变量属性窗格中，您可以重命名变量，查看变量使用位置，或者将变量转换为全局变量。 但是，不能将其从全局变量转换回主题变量。 您还可以选择它是可以接收值，还是可以将其值传递给其他主题。

要打开变量属性窗格，请在变量窗格中选择变量。 您还可以通过在任何节点中选择一个变量来打开变量属性窗格。

系统变量

每个助手均附带内置系统变量，这些变量可提供有关对话的附加信息。

并非所有系统变量都会显示在列表中。 您必须使用 Power Fx 公式来访问这些隐藏的系统变量。

要在 Power Fx 公式中使用系统变量，则必须在变量名称前面添加 System.。 例如，要在公式中包含系统变量 User.DisplayName，您需要将其引用为 System.User.DisplayName。

客户	类型​​	已隐藏	定义
Activity.Channel	选项	可见	当前对话的渠道 ID
Activity.ChannelData	任意	已隐藏	一个包含渠道特定内容的对象
Activity.ChannelId	string	已隐藏	字符串形式的当前对话的渠道 ID
Activity.From.Id	string	已隐藏	发件人的特定于渠道的唯一 ID
Activity.From.Name	string	已隐藏	发件人的特定于渠道的用户友好名称
Activity.Name	string	可见	事件的名称
Activity.Text	string	可见	用户发送的最新消息
Activity.Type	选项	可见	活动的类型
Activity.TypeId	string	已隐藏	字符串形式的活动类型
Activity.Value	任意	已隐藏	开放式值
Bot.Name	string	可见	您助手的名称
Channel.DisplayName	string	已隐藏	渠道名称显示
Conversation.Id	string	可见	当前对话的唯一 ID
LastActivity.Id	string	可见	先前发送的活动的 ID
LastMessage.Id	string	可见	用户发送的上一条消息的 ID
LastMessage.Text	string	可见	用户发送的上一条消息
Recognizer.TriggerMessage.Id	string	可见	触发当前主题的用户消息的 ID
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. 保存主题。

经典

实体和变量类型

Microsoft Copilot Studio 使用实体从用户的回复中识别特定类型的信息。 变量类型会在保存时与识别的信息相关联。 变量类型与实体相似。

每个实体或变量类型映射到一个基类型，如下表中所列。 基本类型确定您在使用相应变量构造逻辑表达式时可以使用的运算符。 它还确定您是否可以将变量作为输入参数提供给流或 Bot Framework 技能。

例如，布尔基本类型映射到运算符“is equal to”，可能值为 True 或 False。 数字基本类型为您提供数字运算符，如“is equal to”、“is greater than”或“is greater than or equal to”等。

实体	变量的基类型
多选选项	String
用户的完整响应	String
年限	数
布尔型	布尔型
City	String
Color	String
洲	String
国家或地区	String
日期和时间	String
Duration	String
Email	String
活动	String
语言	String
金钱	String
数	String
顺序	String
组织	String
百分比	数
人员姓名	String
电话号码	String
兴趣点	String
速度	数
州	String
街道地址	String
温度	数
URL	String
粗细	数
邮政编码	String
自定义实体	String

创建变量

在机器人创作画布中，添加一个问题节点。 一个变量将在节点中自动创建。

1. 转到您的机器人的主题页面，打开要添加变量的主题。

2. 选择添加节点 (+)，然后选择提出问题。

   

   一个包含用户回复的变量将自动创建。

   

选取要使用的实体

默认情况下，将创建一个问题节点，其具有多选选项。 要使用不同的预生成或自定义实体，选择要从节点识别的内容。

重命名变量

自动创建的变量带有默认名称。 要重命名变量，选择变量名称，输入新名称，然后选择完成。

在操作节点中使用变量

当您在操作节点中使用变量时，如果其基本类型与为流或 Bot Framework 技能指定的参数类型匹配，您可以将其提供给该参数。 操作节点的输出会生成新变量。

在操作节点中使用文本值

您可以在操作节点中的变量输入字段中键入文字值，而不是从菜单中选择变量。

“分析值”节点

“分析值”节点允许您将一种类型的值转换为另一种类型的值。 向主题添加节点时，选择“添加节点 (+)”，然后选择“变量管理”和“分析值”。

使用“分析值”节点的主要场景侧重于将原始 JSON 或非类型化变量（其值或结构直到运行时才知道；例如 ChannelData）转换为具体类型。

该流程在调用流时启动，而此流则会调用 API。 然后，API 返回结果。 通常，您需要解析此响应并将一个或多个原始变量返回给 Microsoft Copilot Studio。 使用“分析值”节点，可以将整个 API 结果作为字符串发送：

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

使用这个新节点，您现在拥有的字符串变量可以通过 Power Fx 中的全面智能感知支持转换为记录变量。 使用示例数据的示例将有助于说明此过程。

使用“分析值”节点的示例

1. 添加“分析值”节点，然后选择要解析的变量。

   

2. 选择数据类型。 在这种情况下，请选择“从示例数据”。

   

3. 现在您可以通过单击“从示例 JSON 获取架构”来提供 JSON。 单击此按钮将打开一个编辑器，您可以在其中粘贴示例。

   

4. 最后，指定要将解析值放入哪个变量中。 通常要为此创建一个新变量。

   

   请注意，输出变量现在是正确的类型 - 记录。

   

现在您可以使用新变量。 在 Power Fx 编辑器中，您可以看到您获得了各种属性的完整智能感知。

除了分析 JSON 字符串之外，“分析值”节点的一个关键用途是在运行时分析 UntypedObjects。 当您收到一个事件并且您需要分析“事件”值时可能最常见。 或者您可能想要分析 System.Activity.ChannelData 属性，该属性在运行时因渠道而异。

在下面的示例中，如果事件来自 Teams，您将需要使用 Teams 开发人员文档来查找传入事件的外观的示例，然后使用本节概述的示例数据。

在主题之间传递变量

当您重定向到其他主题时，可以将值传递给目标主题中的变量或从中获取变量。 当您已经有主题所需的信息时，在主题之间传递变量特别有用。 您的用户会很高兴不必再次回答问题。 这在您重构主题并将主题划分为可重用组件，以及您希望跨主题传递变量时会很有帮助。

备注

Custom Entity、Date and Time、Duration 和 Multiple-choice 类型的变量不能在主题之间传递。

接收其他主题中的值

当主题定义变量时（例如，通过问题节点），机器人会询问用户问题来填写变量值。 如果机器人已获取值，则没有理由再次提问。 在这些情况下，您可以将变量定义为接收其他主题中的值。 当另一个主题重定向到此主题时，它可以将一个变量（或文字值）传递给此变量，并会跳过问题。 用户与机器人交谈的体验是无缝的。

要接收其他主题中的值，请设置变量的属性：

1. 在问题节点中，选择要从其他主题接收值的变量。

2. 在变量属性窗格中，在主题(有限范围)下选择接收其他主题中的值。

   

3. 保存主题。

4. 转到您要重定向到的主题。 按照重定向到其他主题中的步骤重定向到正确的主题。

5. 选择 + 为目标主题添加输入。

   

6. 在要将变量传递到的重定向主题中选择变量。

   

7. 在输入或选择一个值下，在当前主题中选择要传递到重定向主题的变量。

   

   变量将显示在重定向节点中。

   

将值返回到原始主题

当主题询问问题，或以其他方式从操作获取变量时，此变量可以返回到重定向到它的原始主题。

在这种情况下，此变量还将成为原始主题的一部分，可以像任何其他变量一样使用。 这可以帮助您构造主题，使机器人获取的信息可跨主题提供，从而减少对全局变量的需要。

要将变量返回到原始主题，请设置变量的属性：

1. 在问题节点中，选择要从其他主题接收值的变量。

2. 在变量属性窗格中，在主题(有限范围)下选择将值返回到原始主题。

   

3. 保存主题。

4. 转到您要重定向到的主题。 按照重定向到其他主题中的步骤重定向到正确的主题。

   返回到主题的变量将显示在重定向的主题中。 在您的主题中使用返回的变量。

   

使用“变量”窗格

使用变量窗格可以一次选择多个变量的接收或返回状态。

1. 在主题的菜单栏中，选择变量。

   

2. 对于主题中的每个变量，选择是要在主题之间传递、接收还是传递并接收值。

   

在变量输入中使用文字值

您可以将文字值和变量传递给主题。 要传递文字值，键入要用作输入的值，而不是选择变量。

相关主题

• 在主题间重用变量
• 自定义助手的外观