使用全局变量

2025-05-22

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

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

重用变量的一种方法是将变量从一个主题传递到另一个主题。另一种方法是使变量在范围内成为全局变量，这是本文介绍的内容。之所以这样称呼全局变量，是因为它们在整个代理的所有主题中都可用。它们也可以从外部源进行设置。

全局变量在单个用户会话期间应用。您指定应将哪些变量属于全局变量，以将其与主题级变量区分开来。

创建全局变量

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

备注

全局变量的名称在所有主题中必须是唯一的。

Web 应用程序
经典/Teams

创建变量或使用变量面板打开现有变量。
在变量属性面板上，选择全局(任何主题均可访问)。

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

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

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

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

Web 应用程序
经典/Teams

在创作画布上或变量面板中选择所需的全局变量。
在变量属性面板的引用部分，选择查看所有引用。
切换到其他选项卡，选择使用变量的任何主题，即可直接转到该主题和节点。

删除全局变量

如果删除其他主题中使用的全局变量，主题中对该变量的引用将被标记为 Unknown。在确认操作之前，您会收到有关删除全局变量的警告。

包含已删除全局变量引用的节点表示包含未知变量。

包含已删除全局变量引用的节点的主题可能会停止工作。请确保在发布代理前删除或更正所有使用已删除变量的主题。

全局变量的生命周期

Web 应用程序
经典/Teams

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

全局变量可从任何主题访问，其值在整个会话中持续存在。

仅当代理用户被重定向到从头开始系统主题，或用户直接触发此主题（例如，通过键入“从头开始”）时，此值才会被清除。在这种情况下，所有全局变量都会重置，并且没有值。

全局变量初始化

如果全局变量在初始化（或“填充”）前被触发，代理会自动触发首次定义全局变量的主题部分 - 即使是在不同的主题中 - 然后再返回原始主题。这种行为允许代理在不中断对话的情况下填写所有变量。

例如，客户在使用全局变量 bot.UserName 的“约会预订”主题中开始对话。但是，bot.UserName 变量最初是在“欢迎”主题中定义的。

当对话到达“约会预订”主题中引用 bot.UserName 的点时，代理将无缝转向首次定义 bot.UserName 的问题节点。

客户回答问题后，代理将恢复“约会预订”主题。

通过 Power Automate 流或技能执行操作时的全局变量行为

有时，您可能会使用流或技能来初始化或填充变量。

但是，当用户与代理进行交互时，可能会在会话中提前填写变量，或者您可能已经在外部设置了变量。

在这种情况下，流或技能仍会运行并填入变量，覆盖之前存储在变量中的内容。

从外部设置全局变量

Web 应用程序
经典/Teams

要确保代理启动具有特定上下文的对话，您可以使用全局变量并从外部源设置其值。假设您的站点要求用户登录。如果将用户名存储在全局变量中并将其传递给代理，则代理可以在客户开始键入第一个问题之前按名称问候客户。另一个示例场景是将上下文从 Dynamics 365 Customer Service 传递给代理，以便它可以在了解客户想要实现的目标的情况下开始对话。

为了防止不必要的延迟，您可以指定代理可以等待值的时间。您还可以设置在外部源无法及时响应时使用的默认值。

备注

发布到 IVR 用例的 Dynamics 365 Contact Center 通道的代理不支持为外部源设置的全局变量配置的超时值。

创建一个专用主题来保存要从外部源设置的所有变量的配置。例如，您可以将此主题命名为“设置上下文变量”。此主题不用于任何其他用途，因此不需要设置触发短语。
在专用主题中添加设置变量值节点。
在设置变量下打开变量选择器，并选择创建新变量。
选择新变量的默认名称。将出现变量属性面板。
将默认名称改为与外部系统传入的变量名称 xactly 一致的名称。
在用途下，选择全局（任何主题都可以访问）和外部来源可以设置值。
在引用下，选择右上角的三个点（⋮），并选择如果为空，则从该节点获取值。
（可选）设置超时延迟（以毫秒为单位）。该值决定了智能体可以等待多久才能从外部来源设置变量，然后才会超时并继续使用设置变量值节点中设置的默认值。此设置在变量依赖于长时间运行或异步进程的方案中相关，但代理必须遵守最大延迟以确保良好的用户体验。

对于来自 Customer Service 全渠道的变量，我们建议将值 10 秒（10,000 毫秒）作为最长等待时间。
在设置变量值节点中，输入超时时要使用的默认值。在运行时，代理将需要具有相同数据类型的值。如果希望默认值为空字符串，请使用 Text("") 作为公式。
对于任何其他预期来自外部系统的值，请在专用主题中添加更多设置变量值节点，并以相同方式配置所需的全局变量。

配置完成后，您的代理就可以进行测试了。调用代理时，代理可以立即开始发送任何不依赖于传入的变量的消息，而不是无限期地等待所有变量被填充。当代理尝试访问在外部设置的变量时，它会暂停，直到值到达或发生超时。了解有关优化智能体以尽量减少延迟的更多信息。

重要提示

在对话的正常流中，如果您的智能体设置了一个变量，而该变量本应是外部值，则以您的智能体内部设置的值为准。在上下文中传递的任何值都将被忽略。此规则可防止代理覆盖主题中有意设置的值。

在嵌入式代理中设置全局变量

Web 应用程序
经典/Teams

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

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

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

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

例如:

您有一个名称为 Global.UserName 的全局变量。
您的代理的 URL 是 https://web.powerva.microsoft.com/webchat/bots/12345。
要在网站上启动代理对话时传入用户名，您可以将 UserName= 查询字符串附加为：https://web.powerva.microsoft.com/webchat/bots/12345?UserName=Ana。

参数名称不区分大小写。 username=Ana 也适用于本示例。

如果只是将代理嵌入到单个网页中则追加变量及其定义，也可以使用 <script> 代码块以编程方式调用和使用变量。

备注

查询字符串的变量名称必须与不含 bot. 前缀的全局变量名称匹配。例如，全局变量 bot.UserEmail 必须显示为 UserEmail=。

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

将变量及其定义作为查询字符串参数（以 botURL?variableName1=variableDefinition1&variableName2=variableDefinition2 格式）追加到代理的 URL，例如：
- 您有一个名称为 bot.UserEmail 的全局变量。
- 您的代理的 URL 是 https://web.powerva.microsoft.com/webchat/bots/12345。
- 要在网站上启动代理对话时传入用户名，您可以将 UserEmail= 查询字符串附加为：https://web.powerva.microsoft.com/webchat/bots/12345?UserEmail=Ana@contoso.com。
参数名称不区分大小写。也就是说，useremail=Ana@contoso.com 在本例中也可以使用。

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

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

Web 应用程序
经典/Teams

在您有代理的页面中的 <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);
    });

嵌入代理时，在 <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));

在您有代理的页面中的 <script> 部分，按照下面的方法定义变量，并将 variableName1 替换为不含 bot. 前缀的变量名称，将 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);
    });

嵌入代理时，在 <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));

根据代理的身份验证设置，会有一组与所选身份验证提供程序相关的全局变量。有关可用的变量集以及如何使用这些变量的详细信息，请参阅将用户身份验证添加到主题。

通过

使用全局变量

创建全局变量

使用全局变量

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

删除全局变量

全局变量的生命周期

从外部设置全局变量

在嵌入式代理中设置全局变量

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

与身份验证相关的全局变量

相关内容

反馈

其他资源