使用变量

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

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

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

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

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

变量类型

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

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

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

在测试 Copilot 时,变量可能会暂时显示为 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 个字符。

选取要使用的实体

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

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

重命名变量

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

  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 创作者不能修改 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. 要仅授权环境中的特定助手使用此密钥保管库,请创建一个标记 AllowedCopilots,并将助手标识符设置为格式 {envId}/{schemaName}。 对于多个值,用逗号分隔这些值。

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

密码值在对话运行时缓存五分钟。 不成功的读取会缓存 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 选项 为生成式操作考虑的动态客户端插件操作的集合
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 进行手动身份验证的变量

当您将 copilot 配置为使用 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 标头字符串。

在主题之间传递变量

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

接收其他主题中的值

当主题定义变量时(例如,在“问题”节点中),助手会询问用户问题来填写变量值。 如果助手在前面的主题中已获取值,则没有理由再次提问。 在这些情况下,您可以将变量设置为接收其他主题中的值。 当另一个主题重定向到此主题时,它可以将任一变量值(或文字值)传递给此变量,并会跳过问题。 用户与助手的交谈体验可以达到无缝状态。

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

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

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

如“测试助手”窗格中所示,如果首先触发此主题,则它会询问用户“我应该怎么称呼你?”它会将值存储在名为 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. 添加重定向节点 并选择目标主题。

  3. 选择 + 添加输入,然后从要向其传递值的目标主题中选择变量。

    在重定向节点中添加 userName 变量作为输入的问候主题的屏幕截图。

  4. 选择 > 图标,然后选择要传递其值的变量。

    选择了 UserName 变量值的问候主题的屏幕截图。

    “重定向”节点应如下所示:

    带有已完成重定向节点的问候主题的屏幕截图。

  5. 保存主题。

将值返回到原始主题

当一个主题通过提问或其他方式被重定向到并获取一个变量时,该变量可以返回到原始主题。 此变量会成为原始主题的一部分,可以像任何其他变量一样使用。 因此,助手获取的信息可跨主题提供,从而减少对全局变量的需要。

我们继续上一节中的示例。 我们将在“与客户交谈”主题中提出一个新问题,然后将答案返回到“问候语”主题。

为返回的变量设置源主题

当您将变量返回到主题时,源主题是被重定向到的主题,即提供将传递回原始主题的值的主题。 在此示例中,它是“与客户交谈”。

  1. 转到源主题。

  2. 添加问题节点并输入消息 What city do you live in?

  3. 识别下面,选择预生成的实体城市

  4. 选择变量以打开变量属性窗格。 将其命名为 userCity,然后选择将值返回到原始主题

    突出显示 userCity 变量及其属性的“与客户交谈”主题的屏幕截图。

  5. 保存主题。

为返回的变量设置目标主题

当您将变量返回给主题时,目标主题是进行重定向的主题,即将从其他主题接收值的主题。 在本示例中,此主题为“问候语”。

  1. 转到目标主题。

  2. 您在源主题中选择的变量应该作为输出变量出现在“重定向”节点中。

    重定向节点中有返回变量的问候主题对话流的屏幕截图。

  3. 保存主题。