使用变量

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

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

变量类型

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

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

在测试 Copilot 时，变量可能会暂时显示为 unknown 类型。 未知 变量尚无值。

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

实体

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

创建变量

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

选取要使用的实体

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

重命名变量

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

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

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

设置变量

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

1. 选择添加节点（+）以添加节点，然后选择变量管理>设置变量值。

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

   

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

   

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

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

使用文字值

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

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

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

变量窗格

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

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

变量属性窗格

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

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

环境变量

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

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

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

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

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

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

若要在 Power Apps 门户中创建机密环境变量，必须 配置其 Key Vault。

此外，您必须执行以下操作才能授权 Copilot Studio 读取此 Key Vault：

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

2. 要授权环境中的所有助手访问密码，请在密码上创建标签 AllowedEnvironments 并添加允许的环境 ID，用逗号分隔。

3. 要仅授权环境中的特定助手使用此密钥保管库，请创建一个标记 AllowedCopilots，并将助手标识符设置为格式 {envId}/{schemaName}。 对于多个值，用逗号分隔这些值。

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

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

系统变量

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

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

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

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

以下变量可用于配置为使用 Microsoft Entra ID 身份验证的 Copilot。 这是新 Copilot 的默认配置。

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

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

以下变量可用于配置为使用通用 OAuth 2 服务提供商的 Copilot。

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

以下变量可用于配置为使用 ID（以前 Microsoft Entra ）服务提供商的 Azure Active DirectoryCopilot。

启用语音的助手的变量

以下变量仅在启用语音的助手上可用。

在主题之间传递变量

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

接收其他主题中的值

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

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

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

如“测试助手”窗格中所示，如果首先触发此主题，则它会询问用户“我应该怎么称呼你？”它会将值存储在名为 userName 的字符串变量中。 userName 变量也可以设置为从其他主题获取其值。 该主题以消息“我希望你今天过得愉快，{userName}！”结束

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

如“测试助手”窗格中所示，如果首先触发此主题，则它会询问用户“你叫什么名字？”它会将值存储在名为 UserName 的字符串变量中。 此主题发送消息“很高兴认识你，{UserName}！”，然后它重定向到“与客户交谈”主题，该主题发送消息“我希望你今天过得愉快，{userName}！”但是请注意，“与客户交谈”主题跳过了再次询问用户姓名这一步骤。 相反，它使用从“问候语”主题传递的 UserName 变量的值。

最后，再次进行第二次对话，这次是从“与客户交谈”主题的角度出发：

我们来演练一下设置主题以从其他主题接收值的步骤。 我们将使用当前的示例，但只要主题需要从较早的主题中获取值，相同的步骤就会起作用。

设置目标主题

目标主题是被重定向到的主题，该主题将从其他主题接收值。 在我们的示例中，它是“与客户交谈”。

1. 创建或转到目标主题。

2. 添加问题节点并输入消息 What should I call you?。

3. 在识别下面，选择预生成的实体人员姓名。

4. 选择变量以打开变量属性窗格。 将其命名为 userName，然后选择接收其他主题中的值。

   

5. 添加 Message 节点。

6. 在消息框中，键入 I hope you're having a wonderful day,。

7. 选择插入变量图标 ({x})，然后选择 userName。

8. 选择变量后面的空格并键入 !。

9. 保存主题。

设置源主题

源主题是进行重定向的主题，它提供将传递给目标主题的值。 在本示例中，此主题为“问候语”。

1. 转到源主题。

2. 添加 Redirect 节点 并选择目标主题。

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

   

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

   

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

   

5. 保存主题。

将值返回到原始主题

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

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

为返回的变量设置源主题

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

1. 转到源主题。

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

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

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

   

5. 保存主题。

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

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

1. 转到目标主题。

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

   

3. 保存主题。

实体和变量类型

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

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

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

创建变量

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

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

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

   

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

   

选取要使用的实体

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

重命名变量

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

在操作节点中使用变量

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

在操作节点中使用文本值

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

“分析值”节点

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

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

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

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

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

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

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

   

2. 选择数据类型。 在本例中，选择 “From Sample Data”（从样本数据）。

   

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

   

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

   

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

   

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

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

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

在主题之间传递变量

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

接收其他主题中的值

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

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

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

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

   

3. 保存主题。

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

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

   

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

   

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

   

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

   

将值返回到原始主题

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

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

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

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

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

   

3. 保存主题。

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

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

   

使用“变量”窗格

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

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

   

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

   

在变量输入中使用文字值

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