使用变量

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

还可以使用变量创建逻辑表达式以沿着不同对话路径动态传递客户。 例如,将客户的名称保存在名为 UserName 的变量中,随着对话的继续,代理可以按名称称呼客户。

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

变量可以存在于四个级别或范围中:

  • 主题 变量只能在创建它们的主题中使用。 此范围是您创建的变量的默认范围。
  • 全局变量 可用于所有主题。 您可以更改主题变量的范围以使主题变量成为全局变量。
  • 系统变量 是使用代理自动创建的。 它们提供有关对话或用户的更多上下文信息。 它们可用于所有主题。
  • 环境变量 是在中创建 Power Platform 的,并且是只读的 Copilot Studio。 它们存储参数键和值,然后作为各种其他应用程序对象的输入,包括 Copilot Studio。 将参数与使用的对象分开可以在同一环境中或在将解决方案迁移到其他环境时更改值。 另一种选择是将硬编码参数值保留在使用它们的组件中。

变量类型

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

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

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

当您测试代理时,变量可能会暂时显示为 unknown 类型。 尚未为未知变量分配值。

变量的顺序从创作画布的顶部向底部确定。 创作画布顶部的节点先于底部的节点考虑。

当创建包含条件节点的分支时,分支按从左到右的顺序排序。 最左侧分支中的节点被视为最右侧分支中的节点之前。

实体

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

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

创建变量

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

问题节点的屏幕截图,突出显示默认变量的名称和类型。

小费

重命名节点,使其更容易识别。 选择节点的名称字段以直接更新名称,或者选择节点的更多图标 (),然后从菜单中选择重命名。 您也可以在代码编辑器中重命名节点。

无法重命名触发器节点和转到步骤节点。

节点名称最长可达 500 个字符。

选取要使用的实体

默认情况下,问题 节点是使用多选选项创建的。 要使用其他预构建或自定义实体,请选择 Identify(识别) 框,然后选择代理应侦听的信息类型。

问题节点的屏幕截图,“选择要标识的信息”菜单打开,“人员姓名”实体突出显示。

重命名变量

创建变量时会自动为变量分配一个名称。 最佳做法是给变量起有意义的名字,让必须维护代理的其他人清楚地知道它们的用途。

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

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

设置变量

通常,您可以使用 Question(问题 节点将用户输入保存到变量中。 但是,在某些情况下,您可能希望自己设置该值。 在这种情况下,请使用设置变量值节点。

  1. 选择添加节点+)以添加节点,然后选择变量管理>设置变量值

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

    “创建新变量”按钮的屏幕截图。

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

    带有未知类型的新变量的“设置变量值”节点的屏幕截图。

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

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

备注

在设置字符串类型变量时,如果遇到 Set variable To value 不匹配,则会显示错误消息和 Fix type mismatch 按钮。 选择该按钮以 Copilot Studio 自动生成 Power Fx 解决不匹配的公式

使用文字值

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

显示为名为 productName 的变量使用文字值的屏幕截图。

显示重定向节点中变量的输入为文字值的屏幕截图。

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

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

变量窗格

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

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

Copilot Studio 创作画布中“变量”窗格的屏幕截图,突出显示“变量”按钮。

变量属性窗格

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

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

变量属性窗格的屏幕截图。

环境变量

环境变量 是一个 Power Platform 概念。 环境变量支持在 Power Platform 环境之间移动应用程序的基本应用程序生命周期管理 (ALM) 方案。 在这种情况下,除了源环境和目标环境之间的一些关键外部引用不同之外,应用程序保持完全相同。

使用环境变量的方式与使用主题全局系统变量的方式相同。 一个显著的区别是,您只能在只读模式下使用环境变量。 代理作者无法修改环境变量。 Copilot Studio 但是,管理员可以在 PowerApps 门户中更改环境变量的值。

将变量值设置为环境变量的主题页面的屏幕截图。

Copilot Studio 中的环境变量类型映射到 PowerApps 数据类型,如下所示:

键入 Copilot Studio 键入 PowerApps
十进制数 数字
JSON 从值中检测类型。 如果不是 Json => 未指定(验证错误)
文本 string
是/否 布尔型
Data source string
机密 String

备注

测试聊天中和发布时,环境变量错误是可见的。 但是,这些错误不会显示在主题列表中,因为它们不是主题变量。

您不能在 Copilot Studio 中创作或编辑环境变量。 您必须使用 PowerApps 门户来更改或设置环境变量。 在 Copilot Studio 中,您可以使用变量窗格查看有关环境变量的信息。 变量窗格也有一个指向本机创作体验的链接。

将环境变量用于 Azure Key Vault 密码

环境变量可以引用密钥保管库中的密码。 这是环境变量的一种特殊情况,需要特别考虑。

要在 PowerApps 门户中创建密码环境变量,您必须配置其密钥保管库

除了上述配置之外,您还必须执行以下操作来授权 Copilot Studio 读取此密钥保管库:

  1. Key Vault Secrets User 角色分配给 Microsoft Virtual Agents Service 应用程序。

  2. 要授权环境中的所有代理访问密钥,请在密钥上创建一个标签 AllowedEnvironments ,并添加允许的环境 ID(以逗号分隔)。

  3. 若要仅授权环境中的特定代理使用此 Key Vault,请创建一个标记 AllowedAgents 并将代理标识符采用以下格式 {envId}/{schemaName}。 对于多个值,用逗号分隔这些值。

如果您达到最大字符数但仍需要添加更多代理,请添加另一个具有描述性但唯一名称的标记(例如: AllowedAgents2)。

密码值在对话运行时缓存五分钟。 不成功的读取会缓存 30 秒。

警告

通过在代理中添加密钥,您可以将此密钥的值公开给所有可以在节点中编辑代理的用户环境因为这些用户可以编辑代理以返回节点中的 SendMessage 值。

系统变量

每个代理都带有内置的系统变量,用于提供有关对话的其他信息。

代理主题中系统变量的屏幕截图。

备注

有关启用语音的代理变量的更多信息,请参阅 使用语音变量

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

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

客户 类型​​ 定义
Activity.Attachments 用户提供的文件附件
Activity.Channel 选项 当前对话的渠道 ID
Activity.ChannelData 任意 一个包含渠道特定内容的对象
Activity.ChannelId string 字符串形式的当前对话的渠道 ID
Activity.From.Id string 发件人的特定于渠道的唯一 ID
Activity.From.Name string 发件人的特定于渠道的用户友好名称
Activity.Name string 事件的名称
Activity.Recipient.Id string 传入活动的类型属性。
Activity.Recipient.Name string 表示通道中代理的显示名称。 在电话渠道上下文中,此变量的值将是代理附加到的电话号码。
Activity.Text string 用户发送的最新消息
Activity.Type 选项 活动的类型
Activity.TypeId string 字符串形式的活动类型
Activity.Value 任意 开放式值
Bot.EnvironmentId string 代理的环境 ID
Bot.Id string #的 ID 代理
Bot.Name string 你的代理
Bot.SchemaName string #的架构名称代理
Bot.TenantId string #的租户 ID 代理
ClientPluginActions 选项 生成式编排需要考虑的 Dynamic Client Plugin Actions 集合
Conversation.Id string 当前对话的唯一 ID
Conversation.InTestMode boolean 表示对话是否在测试画布中进行的布尔标志
Conversation.LocalTimeZone string 用户使用的时区名称,采用 IANA 时区数据库格式
Conversation.LocalTimeZoneOffset datetime 当前本地时区相对于 UTC 的时间偏移量
Error.Code string

当前错误的错误代码。

:仅当扳机键受 On Error支持时,才支持此变量。

Error.Message string

当前错误的错误信息。

:仅当扳机键受 On Error支持时,才支持此变量。

FallbackCount 数字

此变量计算一个主题与用户输入不匹配的次数。

:仅当扳机键受 On Unknown Intent支持时,才支持此变量。

InactivityTimer.Continue boolean

表示计时器是否需要继续的布尔标志。

:仅当扳机键受 Inactivity支持时,才支持此变量。

InactivityTimer.Count 数字

在配置的时间后,由于用户不活动而触发 OnInactivity 计时器的次数。

:仅当扳机键受 Inactivity支持时,才支持此变量。

LastMessage.Id string 用户发送的上一条消息的 ID
LastMessage.Text string 用户发送的上一条消息
Recognizer.ExtractedEntities 选项

表示从触发消息中提取的实体。

:仅当扳机键受 On Select Intent支持时,才支持此变量。

Recognizer.IntentOptions 选项

表示识别器返回不明确结果时的意图选项。

:仅当扳机键受 On Select Intent支持时,才支持此变量。

Recognizer.SelectedIntent 选项

表示从识别器中选择的意图。

:仅当扳机键受 On Select Intent支持时,才支持此变量。

Recognizer.TriggeringMessage.Id string 触发当前主题的用户消息的 ID
Recognizer.TriggeringMessage.Text string 触发当前主题的用户消息
Recognizer.MultipleTopicsMatchedReason string

用于确定匹配多个主题的原因。

:仅当扳机键受 On Select Intent支持时,才支持此变量。

User.Language 选项 此变量用于设置每个对话的用户语言环境。
SignInReason 选项

用于确定触发主题时需要什么登录选项。

:仅当扳机键受 On Sign In支持时,才支持此变量。

集成式身份验证的变量(默认)

当您将代理配置为使用 Microsoft 进行身份验证时,以下变量可用。 这将使用 Entra ID 进行身份验证,并且只允许 Teams 和 PowerApps 渠道。 这是新代理的默认设置。

有关更多信息,请参阅 身份验证变量

客户 类型​​ 定义
User.DisplayName string 当前与代理对话的用户的显示名称。
User.Email string 当前与代理对话的用户的电子邮件地址。
User.FirstName string 当前与代理对话的用户的名。
User.Id string 当前与代理通信的用户的唯一 ID。
User.IsLoggedIn boolean 布尔表示当前与代理通信的用户是否经过身份验证的标志。
User.LastName string 当前与代理对话的用户的姓。
User.PrincipalName string 当前与代理通信的用户的用户主体名称。

使用 Generic OAuth 2 进行手动身份验证的变量

当您将代理配置为使用 Generic OAuth 2 服务提供商时,以下变量可用。

客户 类型​​ 定义
User.AccessToken string 使用代理进行身份验证的用户的访问令牌。
User.DisplayName string 当前与代理对话的用户的显示名称。
User.Id string 当前与代理通信的用户的唯一 ID。
User.IsLoggedIn boolean 布尔表示当前与代理通信的用户是否经过身份验证的标志。

使用 Microsoft Entra ID 进行手动身份验证的变量

当您将代理配置为使用 Microsoft Entra ID(以前 Azure Active Directory)服务提供商时,以下变量可用。

客户 类型​​ 定义
User.AccessToken string 使用代理进行身份验证的用户的访问令牌。
User.DisplayName string 当前与代理对话的用户的显示名称。
User.Email string 当前与代理对话的用户的电子邮件地址。
User.FirstName string 当前与代理对话的用户的名。
User.Id string 当前与代理通信的用户的唯一 ID。
User.IsLoggedIn boolean 布尔表示当前与代理通信的用户是否经过身份验证的标志。
User.LastName string 当前与代理对话的用户的姓。
User.PrincipalName string 当前与代理通信的用户的用户主体名称。

支持语音的代理的变量

以下变量仅在支持语音的代理中可用。

备注

有关启用语音的代理变量的更多信息,请参阅 使用语音变量

客户 类型​​ 定义
Activity.InputDTMFKeys string 从电话服务接收的原始 DTMF 键值。
Activity.SpeechRecognition.Confidence 数字 ASR 假设整体结果的置信度得分,从 0 到 1。
Activity.SpeechRecognition.MinimallyFormattedText string ASR 假设结果的稍微格式化的文本。 例如,五百美元。 单词已拼写完成,但包括基本的大写和标点符号。
Activity.UserInputType 选项 终端用户最近输入的输入类型。 该值可以是 test、speech 或 DTMF。
Conversation.OnlyAllowDTMF boolean 表示 IVR 是否应该在运行时设置为仅 DTMF 模式的布尔标志。
Conversation.SipUuiHeaderValue string 用于在呼叫开始时将上下文传递到 IVR 的 UUI 标头字符串。

在主题之间传递变量

当您将一个主题重新定向到另一个主题时,可以在原始主题与目标主题之间传递变量值。 当前面的主题已经收集了后面的主题需要的信息时,在主题之间传递变量特别有用。 您的用户会很高兴不必再次回答相同的问题。

接收其他主题中的值

当主题定义变量时(例如,在 Question 节点中),代理会询问用户问题以填写变量的值。 如果代理已经在较早的主题中获得了该值,则没有理由再次询问该问题。 在这些情况下,您可以将变量设置为接收其他主题中的值。 当另一个主题重定向到此主题时,它可以将任一变量值(或文字值)传递给此变量,并会跳过问题。 用户与代理交谈的体验是无缝的。

在此示例中,我们将使用“问候语”和“与客户交谈”这两个主题。 这两个主题都询问客户的名称。 但是,如果“问候语”主题先运行,“与客户交谈”主题会跳过它的问题。 相反,它使用从“问候语”主题传递的变量的值。

下面是“与客户交谈”主题的流:

“与客户交谈”主题对话流的屏幕截图。

如 Test 代理(测试 #)窗格中所示,如果首先触发此主题,它会询问用户,“我应该给您打电话吗?它将值存储在名为 userName userName 变量也可以设置为从其他主题获取其值。 该主题以消息“我希望你今天过得愉快,{userName}!”结束

下面是“问候语”主题的流:

“问候”主题对话流的屏幕截图。

如 Test 代理(测试 #)窗格中所示,如果首先触发此主题,它会询问用户“你叫什么名字?它将值存储在名为 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. 保存主题。