在主题间重用变量

  • 项目

重要提示

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

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

变量存储客户对助手的问题的回复。 例如，可将一个客户的姓名保存到名称为 UserName 的变量中。 然后，助手可在对话继续时按姓名识别该客户。

默认情况下，变量的值只能在创建变量的主题中使用。 但是，可以跨主题重复使用同一值。 例如，“欢迎”主题将询问客户的姓名和电子邮件地址。 在“预约”主题中，您希望助手记住客户输入的内容并且不再询问。

重用变量的一种方法是在主题之间传递变量。 另一种方法是使变量在范围内成为全局变量，这是本文介绍的内容。 之所以称为全局变量，是因为它们在整个助手的所有主题中都可用。

Copilot 变量在单个用户会话期间应用。 您指定应将哪些变量视为助手变量，以将其与主题级变量区分开来。

创建全局变量

您可以通过更改主题变量的范围来创建全局变量。

  1. 创建变量或使用变量窗格打开现有变量。

  2. 在变量属性窗格上，选择全局(任何主题均可访问)。

    将为变量名称提供前缀 Global.，以将其与主题级变量区分开来。 例如，变量 UserName 会显示为 Global.UserName。

    显示“变量属性”窗格的屏幕截图，其中突出显示了全局设置。

  3. 保存主题。

    全局变量的名称在所有主题中都必须唯一。 如果有冲突，您需要在保存主题之前重命名变量。

使用全局变量

当您在“消息”节点或“问题”节点中撰写助手消息时，请选择 {x} 图标以查看主题可用的变量。 全局变量会与任何主题变量一起出现在自定义选项卡中。 变量按字母顺序列出。

显示全局变量选择的屏幕截图。

使用全局变量查找所有主题

您可以找到全局变量的定义位置以及哪些其他主题正在使用它。 如果在使用新助手，或者如果有多个变量和复杂主题分支，这可能非常有用。

  1. 在创作画布中选择全局变量，或打开变量窗格，并选择全局变量。

  2. 在变量属性窗格上，在引用部分中，选择将变量直接用于该主题和节点的任一主题。

    显示变量属性窗格中变量使用的主题列表的屏幕截图。

全局变量的生命周期

默认情况下，全局变量的值在会话结束之前将始终存在。 清除变量值节点将重置全局变量的值，并用于重置对话系统主题。 该主题可以通过重定向或在用户键入触发短语（例如“重新开始”）时触发。在这种情况下，所有全局变量都将被重置。

从外部来源设置全局变量的值

如果您想确保助手在某些上下文中开始对话，您可以使用外部源初始化全局变量。 假设您的站点要求用户登录。 由于您的助手已经知道用户的姓名，因此它可以在客户开始输入第一个问题之前按姓名问候客户。

  1. 选择全局变量。

  2. 在变量属性窗格上，选择外部源可以设置值。

在嵌入式助手中设置全局变量

如果您将助手嵌入到一个简单的网页中，则可以将变量及其定义追加到助手的 URL 中。 或者，如果您想要更多控制，可以使用 <script> 代码块以编程方式调用和使用变量。

此 URL 的查询字符串中的变量名称必须与不含 Global. 前缀的全局变量的名称匹配。 例如，全局变量 Global.UserName 在查询中称为 UserName。

下面的示例提供了变量的简单声明。 在生产场景中，您可以作为查询参数或变量定义传递已经存储了用户名称的另一个变量（例如，如果您有来自登录脚本的用户名）。

将变量及其定义作为查询字符串参数（以 botURL?variableName1=variableDefinition1&variableName2=variableDefinition2 格式）追加到助手的 URL。

例如:

参数名称不区分大小写。 username=Renata 在此示例中也有效。

将全局变量添加到自定义画布

您还可以将变量添加到自定义画布中。

  1. 在您有助手的页面中的 <script> 部分，按照下面的方法定义变量，并将 variableName1 替换为不含 Global. 前缀的变量名称，将 variableDefinition1 替换为定义。 使用逗号 (,) 分隔多个变量。

       const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
     if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
       dispatch({
          type: "WEB_CHAT/SEND_EVENT",
          payload: {
            name: "pvaSetContext",
            value: {
               "variableName1": "variableDefinition1",
               "variableName2": "variableDefinition2"
            }
          },
        });
      }
        return next(action);
    });

  2. 嵌入助手时，在 <script> 部分内调用 store，如下面的示例所示，其中，store 仅在调用 styleOptions 的基础上调用（需要将 BOT_ID 替换为您的助手 ID）：

    const BOT_ID = "12345-5678";
const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;

fetch(theURL)
    .then(response => response.json())
    .then(conversationInfo => {
        window.WebChat.renderWebChat(
            {
                directLine: window.WebChat.createDirectLine({
                    token: conversationInfo.token,
                }),
                store,
                styleOptions
            },
            document.getElementById('webchat')
        );
    })
    .catch(err => console.error("An error occurred: " + err));