如何在本地电脑上开发呼叫和联机会议 botHow to develop calling and online meeting bots on your local PC

在 "运行" 和 "调试" 应用程序中,我们将介绍如何使用ngrok在本地计算机和 internet 之间创建隧道。In Run and debug your app we explain how to use ngrok to create a tunnel between your local computer and the internet. 在本主题中,您还可以了解如何使用 ngrok 和本地电脑来开发支持呼叫和联机会议的 bot。In this topic, learn how you can also use ngrok and your local PC to develop bots that support calls and online meetings.

邮件机器人使用 HTTP,但呼叫和联机会议 bot 使用低级别 TCP。Messaging bots use HTTP, but calls and online meeting bots use the lower-level TCP. 除了 HTTP 隧道之外,Ngrok 还支持 TCP 隧道;你将在下面了解如何操作。Ngrok supports TCP tunnels in addition to HTTP tunnels; you'll learn how, below.

配置 ngrok ymlConfiguring ngrok.yml

转到ngrok并注册免费帐户或登录到现有帐户。Go to ngrok and sign up for a free account or log into your existing account. 登录后,请转到仪表板并获取 authtoken。Once you've logged in, go to the dashboard and get your authtoken.

创建 ngrok 配置文件ngrok.yml (有关此文件位于何处的详细信息,请参阅此处),并添加以下行:Create an ngrok configuration file ngrok.yml (see here for more information on where this file can be located) and add this line:

authtoken: <Your-AuthToken>

设置信号Setting up signaling

呼叫和联机会议 bot中,我们讨论了呼叫信号—在呼叫过程中,bot 如何检测和响应新的呼叫和事件。In Calls and online meetings bots, we discussed call signaling — how bots detect and respond to new calls and events during a call. 呼叫信号事件通过 HTTP POST 发送到 bot 的调用终结点。Call signaling events are sent via HTTP POST to the bot's calling endpoint.

与 bot 的邮件 API 一样,为了让实时媒体平台与你的 bot 交流,你的 bot 必须可通过 internet 访问。As with the bot's messaging API, in order for the Real-time Media Platform to talk to your bot, your bot must be reachable over the internet. Ngrok 使此简单-将以下行添加到 Ngrok 中。 yml:Ngrok makes this simple — add the following lines to your ngrok.yml:

tunnels:
    signaling:
        addr: 12345
        proto: http

设置本地媒体Setting up local media

备注

仅应用程序托管的媒体 bot 需要此部分,如果你不自己托管媒体,则可以跳过此部分。This section is only required for application-hosted media bots and can be skipped if you don't host media yourself.

应用程序托管的媒体使用证书和 TCP 隧道。Application-hosted media uses certificates and TCP tunnels. 以下步骤是必需的:The following steps are required:

  • Ngrok 的公共 TCP 终结点具有固定的 Url。Ngrok's public TCP endpoints have fixed URLs. 它们是0.tcp.ngrok.io1.tcp.ngrok.io等。They are 0.tcp.ngrok.io, 1.tcp.ngrok.io, and so on. 您应具有指向这些 Url 的服务的 DNS CNAME 条目。You should have a DNS CNAME entry for your service that points to these URLs. 在此示例中, 0.bot.contoso.com假设引用0.tcp.ngrok.io1.bot.contoso.com引用1.tcp.ngrok.io,等等。In this example, let's say 0.bot.contoso.com refers to 0.tcp.ngrok.io, 1.bot.contoso.com refers to 1.tcp.ngrok.io, and so on.

  • 您的 Url 需要 SSL 证书。A SSL certificate is required for your URLs. 为了便于使用,请使用颁发给通配符域的 SSL 证书。To make it easy, use a SSL certificate issued to a wild card domain. 在这种情况下,应*.bot.contoso.com为。In this case, it would be *.bot.contoso.com. 此 SSL 证书由媒体 SDK 进行验证,因此它应与你的 bot 的公共 URL 相匹配。This SSL certificate is validated by the media SDK, so it should match your bot's public URL. 记下指纹,并将其安装在计算机证书中。Note the thumbprint and install it in your machine certificates.

  • 现在,设置 TCP 隧道以将流量转发到本地主机。Now, setup a TCP tunnel to forward the traffic to localhost. 在 ngrok 中写入以下行: yml:Write the following lines into your ngrok.yml:

    media:
        addr: 8445
        proto: tcp
    

启动 ngrokStart ngrok

现在,ngrok 配置已准备就绪,请启动它:Now that the ngrok configuration is ready, launch it:

ngrok.exe start -all -config <Path to your ngrok.yml>

这将启动 ngrok 并定义提供本地主机隧道的公共 Url。This starts ngrok and defines the public URLs which provide the tunnels to your localhost. 输出外观如下所示:The output looks like the following:

Forwarding  http://signal.ngrok.io -> localhost:12345
Forwarding  https://signal.ngrok.io -> localhost:12345
Forwarding  tcp://1.tcp.ngrok.io:12332 -> localhost:8445

这里12345是信号端口, 8445是应用程序托管的端口, 12332是由 ngrok 公开的远程媒体端口。Here, 12345 is the signaling port, 8445 is the application-hosted port, and 12332 is the remote media port exposed by ngrok. 请注意,我们已从1.bot.contoso.com转到1.tcp.ngrok.ioNote that we have a forwarding from 1.bot.contoso.com to 1.tcp.ngrok.io. 这将用作 bot 的媒体 URL。This will be used as the media URL for the bot. 当然,这些端口号只是示例,您可以使用任何可用的端口。Of course, these port numbers are just examples and you can use any available port.

更新代码Update code

在 ngrok 已启动并在运行后,更新代码以使用刚刚设置的配置。Once ngrok is up and running, update the code to use the config you just set up.

更新信号Update signaling

  • 在 BotBuilder 调用中,将更改NotificationUrl为 ngrok 提供的信号 URL。In the BotBuilder call, change the NotificationUrl to the signaling URL provided by ngrok.
statefulClientBuilder.SetNotificationUrl(
    new Uri("https://signal.ngrok.io/notificationEndpoint"))

备注

将信号替换为 ngrok 提供的和NotificationEndpoint接收通知的控制器路径。Replace signal with the one provided by ngrok and the NotificationEndpoint with the controller path that receives notification.

重要说明:中SetNotificationUrl的 URL 必须是 HTTPS。IMPORTANT: The URL in SetNotificationUrl must be HTTPS.

重要说明:您的本地实例必须侦听信号端口上的 HTTP 流量。IMPORTANT: Your local instance must be listening to HTTP traffic on the signaling port. 呼叫和联机会议平台发出的请求将机器人作为 localhost HTTP 流量,除非设置端到端加密。The requests made by the calls and online meetings platform will reach the bot as localhost HTTP traffic unless end-to-end encryption is set up.

更新媒体Update media

更新MediaPlatformSettings到以下项。Update your MediaPlatformSettings to the following.

var mediaPlatform = new MediaPlatformSettings
{
    ApplicationId = <Your application id>
    MediaPlatformInstanceSettings = new MediaPlatformInstanceSettings
    {
        CertificateThumbprint = <Your SSL Cert thumbprint>,
        InstanceInternalPort = <Localhost media port>,
        InstancePublicPort = <Ngrok exposed remote media port>,
        InstancePublicIPAddress = new IPAddress(0x0),
        ServiceFqdn = <Media url for bot (eg: 1.bot.contoso.com)>,
    },
}

备注

上面提供的证书指纹应与服务 FQDN 相匹配。The certificate thumbprint provided above should match the Service FQDN. 这就是为什么需要 DNS 条目的原因。That is why the DNS entries are required.

后续步骤Next steps

你的 bot 现在可以在本地运行,并且所有流都可以从本地主机运行。Your bot can now run locally and all the flows work from your localhost.

几点Caveats

  • Ngrok 免费帐户提供端到端加密。Ngrok free accounts don't provide end-to-end encryption. HTTPS 数据在 ngrok URL 和从 ngrok 到localhost之间未加密的数据流处结束。The HTTPS data ends at the ngrok URL and the data flows unencrypted from ngrok to localhost. 如果需要端到端加密,请考虑使用付费的 ngrok 帐户。If you require end-to-end encryption, consider a paid ngrok account. 有关设置安全端到端隧道的步骤,请参阅TLS 隧道See TLS tunnels for steps on setting up secure end-to-end tunnels.
  • 由于 bot 回调 URL 是动态的,因此传入呼叫方案要求您频繁更新 ngrok 终结点。Because the bot callback URL is dynamic, incoming call scenarios require you to frequently update your ngrok endpoints. 解决此问题的一种方法是使用付费的 ngrok 帐户,该帐户提供可将你的 bot 和平台指向的固定子域。One way to fix this is to use a paid ngrok account which provides fixed subdomains to which you can point your bot and the platform.
  • Ngrok 隧道也可用于Azure Service FabricNgrok tunnels can also be used with Azure Service Fabric. 有关如何执行此操作的示例,请参阅HueBot 示例应用程序For an example of how to do this, see the HueBot sample app.