变量概述

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

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

变量类型

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

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

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

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

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

当创建包含条件节点的分支时，分支按从左到右的顺序排序。 最左边的分支中的节点先于最右边分支中的节点考虑。

实体

Web 应用程序

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

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

经典

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

环境变量

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

使用环境变量的方式与使用主题、全局和系统变量的方式相同。 一个显著的区别是，环境变量在 Copilot Studio 中是只读的。 在 Copilot Studio 中，代理创作者不能修改环境变量。 但在 Power Apps 中，管理员可以更改环境变量的值。 在 Copilot Studio 中，可以使用变量面板查看环境变量的相关信息。 变量面板也有一个指向本地创作体验的链接。

使用环境变量的代理的已发布版本包含代理发布时为这些变量设置的值。 只要管理员更新了环境变量，就必须重新发布使用这些变量的代理，这样更改才能在运行时生效。 但有一个例外：当密码类型的环境变量的值发生变化时，你不需要重新发布代理。 与其他环境变量不同，密码变量是在运行时检索的。

Copilot Studio 中的环境变量类型映射到 Power Apps 数据类型，如下所示：

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

备注

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

系统变量

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

备注

有关启用语音的代理变量的详细信息，请参阅 使用语音变量。

并非所有系统变量都会显示在列表中。 您必须使用 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	布尔型	表示对话是否在测试画布中进行的布尔标志
Conversation.LocalTimeZone	string	用户使用的时区名称，采用 IANA 时区数据库格式
Conversation.LocalTimeZoneOffset	datetime	当前本地时区相对于 UTC 的时间偏移量
Error.Code	string	当前错误的错误代码。 当前错误的错误信息。
Error.Message	string	当前错误的错误信息。 注：仅当触发器为 On Error 时，才支持此变量。
FallbackCount	数字	此变量计算一个主题与用户输入不匹配的次数。 注：仅当触发器为 On Unknown Intent 时，才支持此变量。
InactivityTimer.Continue	布尔型	表示计时器是否需要继续的布尔标志。 注：仅当触发器为 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 时，才支持此变量。
SignInReason	选项	用于确定触发主题时需要什么登录选项。 注：仅当触发器为 On Sign In 时，才支持此变量。
User.Language	选项	此变量用于设置每个对话的用户语言环境。

集成式身份验证的变量（默认）

以下变量适用于配置为通过 Microsoft 身份验证的代理。 此配置使用 Microsoft Entra ID 身份验证，是新代理的默认配置。

有关详细信息，请参阅身份验证变量。

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

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

下列变量适用于配置为使用通用 OAuth 2 服务提供程序的代理。

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

使用 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	布尔型	布尔标志，表示当前与代理通信的用户是否经过身份验证。
User.LastName	string	当前与代理对话的用户的姓氏。
User.PrincipalName	string	当前与代理对话的用户的主体名称。

支持语音的代理的变量

以下变量仅适用于支持语音的代理。

备注

有关启用语音的代理变量的详细信息，请参阅 使用语音变量。

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