为扩展配置 Node.js 机器人

项目
10/25/2024

从2023年9月1日起，强烈建议使用 Azure 服务标记方法进行网络隔离。 DL-ASE的使用应仅限于高度特定的方案。在生产环境中实施此解决方案之前，我们建议咨询支持团队，以获取他们的指导。

适用于： SDK v4

本文介绍如何更新 Node.js 机器人，使之可以使用命名管道，以及如何在托管机器人的 Azure 应用服务资源中启用 Direct Line 应用服务扩展。

先决条件

一个 Azure 帐户。如果你还没有该订阅，请在开始之前先创建试用版订阅。
在 Azure 中部署的 Node.js 机器人。
Node.js 的 Bot Framework SDK 4.7 或者更新版本。

启用 Direct Line 应用服务扩展

本部分介绍如何使用机器人 Direct Line 通道配置中的应用服务扩展密钥来启用 Direct Line 应用服务扩展。

更新机器人代码

允许应用使用 Direct Line 应用服务扩展命名管道：

编辑机器人的 index.js 文件。

找到创建机器人适配器的行。

创建适配器后，添加以下语句，该语句将从环境中拉取应用服务名称，并指示适配器连接到相应的命名管道。

如果机器人使用（建议）：CloudAdapter

adapter.connectNamedPipe(
    process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline',
    async (context) => {
        await myBot.run(context);
    },
    process.env.MicrosoftAppId,
    AuthenticationConstants.ToChannelFromBotOAuthScope);

如果机器人使用已弃用的 BotFrameworkAdapter：

adapter.useNamedPipe(async (context) => {
    await myBot.run(context);
    },
    process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline'
);

保存所做更改。

编辑机器人的 web.config 文件，向服务请求添加 Direct Line 应用服务扩展所需的 AspNetCore 处理程序和规则。

编辑机器人的 web.config 文件。
将 webSocket 标记的属性 enabled 更改为 true。
```
<webSocket enabled="true" />
```

在本 <handlers> 部分中，添加以下处理程序的注册。

<add name="aspNetCore" path="*/.bot/*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />

在本 <rewrite> 部分中，将以下规则添加到规则列表。

<!-- Do not interfere with Direct Line App Service extension requests. (This rule should be as high in the rules section as possible to avoid conflicts.) -->

<rule name ="DLASE" stopProcessing="true">
  <conditions>
    <add input="{REQUEST_URI}" pattern="^/.bot"/>
  </conditions>
</rule>

保存所做更改。

将更新的机器人重新部署到 Azure。

启用机器人 Direct Line 应用服务扩展

在 Azure 门户中，转到你的 Azure 机器人资源。
1. 在设置中选择通道以配置机器人接受消息的通道。
2. 如果尚未启用，请从可用通道列表中选择 Direct Line 通道以启用通道。
3. 启用 Direct Line 后，从频道页再次选择它。
4. 选择应用服务扩展选项卡。
5. 在应用服务扩展密钥下，选择相应密钥旁边的眼睛图标。
转到主页，选择页面顶部的应用服务。或者，显示门户菜单，然后选择应用服务菜单项。 Azure 将显示应用服务页。
在搜索框中，输入 Azure 机器人资源名称。资源将列出。

请注意，如果将鼠标悬停在图标或菜单项上，将获取上次查看的资源的列表。 可能会列出 Azure 机器人资源。

选择你的资源链接。

在边栏的设置部分中，选择配置菜单项。
在右侧面板中添加以下新设置：

名称值

DirectLineExtensionKey 前面复制的应用服务扩展密钥的值。

DIRECTLINE_EXTENSION_VERSION 最新

名称	值
DirectLineExtensionKey	前面复制的应用服务扩展密钥的值。
DIRECTLINE_EXTENSION_VERSION	最新

如果机器人托管在主权云或其他受限制的 Azure 云中（即，无法通过公共门户访问 Azure），则还需要添加以下新设置：

名称	值
DirectLineExtensionABSEndpoint	机器人托管的特定于 Azure 云的终结点。例如，对于 USGov 云，终结点为 `https://directline.botframework.azure.cn/v3/extension`。

单击配置部分的通用设置部分，启用 Web 套接字。
选择保存，保存这些设置。此时会重启 Azure 应用服务。

确认已配置 Direct Line 应用扩展和机器人

在浏览器中转到 https://<your_app_service>.chinacloudsites.cn/.bot。如果一切正确，页面会返回这样的 JSON 内容：

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}

v 显示 Direct Line 应用服务扩展 (ASE) 的生成版本。
k 指示扩展是否可以从其配置中读取扩展密钥。
initialized 表明扩展是否可以从 Azure AI 机器人服务下载机器人元数据。
ib 表明扩展是否能够建立与机器人的入站连接。
ob 指示扩展是否能够从机器人建立出站连接。

故障排除

如果 .bot endpoint 显示的 ib 和 ob 值为 false，则意味着机器人和 Direct Line 应用服务扩展无法相互连接。
1. 请仔细检查是否已将使用命名管道的代码已添加到机器人。
2. 确认机器人可以完全正常启动和运行。有用的工具包括在 Web 聊天中测试、连接附加通道、远程调试或日志记录。
3. 重启托管机器人的整个 Azure 应用服务，确保干净启动所有进程。
如果 .bot endpoint 的 initialized 值为 false，则意味着 Direct Line 应用服务扩展无法验证添加到机器人的上述应用程序设置的应用服务扩展密钥。
1. 确认输入的值正确。
2. 切换到机器人的 Direct Line 通道配置页上显示的备用应用服务扩展密钥。

后续步骤

将 Web 聊天与 Direct Line 应用服务扩展配合使用

通过