你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：以编程方式配置语音路由

项目
10/19/2023

为 Azure 通信服务直接路由配置出站语音路由规则。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
活动的通信服务资源。创建通信服务资源。
操作电话系统中会话边界控制器 (SBC) 的完全限定的域名 (FQDN) 和端口号。
SBC FQDN 的经验证的域名。

注意

可在 GitHub 上找到更多 SipRoutingClient 的用法示例。

添加会话边界控制器

在左窗格的“语音呼叫 - PSTN”下，选择“直接路由”。在“会话边界控制器”选项卡上，选择“配置”。
输入 SBC 的 FQDN 和信号端口。 SBC FQDN 的要求包括：
- 必须先验证 FQDN 的域部分，然后才能将其添加到直接路由配置，如前面先决条件中所述。
- SBC 证书必须与名称匹配。支持通配符证书。
- 不能将 *.onmicrosoft.com 和 *.azure.com 域用于 FQDN。
有关完整的要求列表，请查看 Azure 直接路由基础结构要求。
选择下一步。如果一切设置正确，应会在 Azure 门户中看到 SBC 的状态是“活动”。

重要

在发出或接听呼叫之前，请确保 SBC 状态为“在线”

创建语音路由规则

为语音路由指定名称，使用正则表达式指定号码模式，然后为该模式选择 SBC。下面是基本正则表达式的一些示例：

^\+\d+$：匹配包含一个或多个数字且以加号开头的电话号码。
^\+1(\d{10})$：匹配 +1 后面有 10 个数字的电话号码。
^\+1(425|206)(\d{7})$：匹配以 +1425 或 +1206 开头并后接 7 个数字的电话号码。
^\+0?1234$：匹配 +01234 和 +1234 电话号码。

有关正则表达式的详细信息，请参阅 .NET 正则表达式概述。

可为单个模式选择多个 SBC。在这种情况下，路由算法按随机顺序选择 SBC。还可以多次指定确切的号码模式。较高的行具有较高的优先级。如果与该行关联的所有 SBC 都不可用，则选择下一行。这样便可以创建复杂的路由方案。

移除直接路由配置

若要删除语音路由，请执行以下操作：

在左侧窗格中的“语音呼叫 - PSTN”下，转到“直接路由”。
在“语音路由”选项卡上，选中要删除的路由的复选框。
选择“删除” 。

若要删除 SBC，请执行以下操作：

在左侧窗格中的“语音呼叫 - PSTN”下，转到“直接路由”。
在“会话边界控制器”选项卡上，选择“配置”。
清除要移除的 SBC 的 FQDN 和端口字段，然后选择“下一步”。
在“语音路由”选项卡上，查看语音路由配置。根据需要进行更改，然后选择“保存”。

移除与某个语音路由关联的 SBC 时，可以在“语音路由”选项卡上为该路由选择其他 SBC。将删除没有 SBC 的语音路由。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
活动的通信服务资源和连接字符串。创建通信服务资源。
适用于你的操作系统的最新版 .NET Core 客户端库。
操作电话系统中会话边界控制器 (SBC) 的完全限定的域名 (FQDN) 和端口号。
SBC FQDN 的经验证的域名。

最终代码

在 GitHub 上查找此快速入门的最终代码。

还可在 GitHub 上找到更多 SipRoutingClient 的用法示例。

创建 C# 应用程序

在控制台窗口（例如命令提示符、PowerShell 或 Bash）中，使用 dotnet new 命令新建控制台应用：

    dotnet new console -o DirectRoutingQuickstart

此命令将创建包含单个源文件的简单“Hello World”C# 项目：Program.cs。

将目录更改为新建的应用文件夹，并使用 dotnet build 命令编译应用程序：

    cd DirectRoutingQuickstart
    dotnet build

安装包

如果仍在应用程序目录中，使用 dotnet add package 命令安装适用于 .NET 的 Azure 通信电话号码客户端库：

    dotnet add package Azure.Communication.PhoneNumbers --version 1.1.0

将 using 指令添加到 Program.cs 顶部以包括命名空间：

using Azure.Communication.PhoneNumbers.SipRouting;

验证客户端

使用 Azure 通信服务资源中的连接字符串验证电话号码客户端：

// Get a connection string to the Azure Communication Services resource.
var connectionString = "<connection_string>";
var client = new SipRoutingClient(connectionString);

设置直接路由配置

在先决条件中，你已验证域所有权。后续步骤是创建中继（添加 SBC）并创建语音路由。

创建或更新中继

Azure 通信服务直接路由仅允许与已注册的 SBC 通信。若要注册 SBC，需要其 FQDN 和端口：

// Register your SBCs by providing their fully qualified domain names and port numbers.
var usSbcFqdn = "sbc.us.contoso.com";
var euSbcFqdn = "sbc.eu.contoso.com";
var sbcPort = 5061;

var usTrunk = new SipTrunk(usSbcFqdn, sbcPort);
var euTrunk = new SipTrunk(euSbcFqdn, sbcPort);

await client.SetTrunksAsync(new List<SipTrunk> { usTrunk, euTrunk });

创建或更新路由

为出站呼叫提供路由规则。每个规则由两部分组成：应匹配拨打的电话号码的正则表达式模式和路由呼叫的已注册中继的 FQDN。

路由顺序决定了路由的优先级。在呼叫时将选择与正则表达式匹配的第一个路由。

在此示例中，为以 +1 开头的号码创建一个路由，为仅以 + 开头的号码创建另一个路由：

var usRoute = new SipTrunkRoute("UsRoute", "^\\+1(\\d{10})$", trunks: new List<string> { usSbcFqdn });
var defaultRoute = new SipTrunkRoute("DefaultRoute", "^\\+\\d+$", trunks: new List<string> { usSbcFqdn, euSbcFqdn });

await client.SetRoutesAsync(new List<SipTrunkRoute> { usRoute, defaultRoute });

更新直接路由配置

通过使用相同的 FQDN 覆盖记录，可更新特定中继的属性。例如，可以设置新的 SBC 端口值：

var usTrunk = new SipTrunk("sbc.us.contoso.com", 5063);
await client.SetTrunkAsync(usTrunk);

使用相同的方法创建和更新路由规则。更新路由时，在一次更新中发送所有路由。新的路由配置将完全覆盖以前的路由配置。

移除直接路由配置

无法编辑或移除单个语音路由。应覆盖整个语音路由配置。下面是移除所有路由和中继的空列表的示例：

//delete all configured voice routes
await client.SetRoutesAsync(new List<SipTrunkRoute>());

//delete all trunks
await client.SetTrunksAsync(new List<SipTrunk>());

可以使用以下示例删除单个中继 (SBC)，前提是没有语音路由正在使用它。如果 SBC 在任何语音路由中列出，请先删除该路由。

await client.DeleteTrunkAsync("sbc.us.contoso.com");

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Java 开发工具包 (JDK) 版本 8 或更高版本。
Apache Maven。
已部署的通信服务资源和连接字符串。创建通信服务资源。
操作电话系统中会话边界控制器 (SBC) 的完全限定的域名 (FQDN) 和端口号。
SBC FQDN 的经验证的域名。

最终代码

在 GitHub 上查找此快速入门的最终代码。

还可在 GitHub 上找到更多 SipRoutingClient 的用法示例。

创建 Java 应用程序

打开终端或命令窗口。转到要用于创建 Java 应用程序的目录。然后，运行该命令以从 maven-archetype-quickstart 模板生成 Java 项目：

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

generate 任务将创建一个名称与 artifactId 值相同的目录。在此目录下，src/main/java 目录包含项目源代码，src/test/java 目录包含测试源，pom.xml 文件是项目的项目对象模型 (POM)。

安装包

在文本编辑器中打开 pom.xml 文件。将以下依赖项元素添加到依赖项组：

<dependencies>
	<dependency>
		<groupId>com.azure</groupId>
		<artifactId>azure-communication-phonenumbers</artifactId>
		<version>1.1.0</version>
	</dependency>
</dependencies>

设置应用框架

从项目目录中执行以下操作：

转到 /src/main/java/com/communication/quickstart 目录。
在编辑器中打开 App.java 文件。
替换 System.out.println("Hello world!"); 语句。
添加 import 指令。

使用以下代码以开始执行以下操作：

import com.azure.communication.phonenumbers.siprouting.SipRoutingAsyncClient;
import com.azure.communication.phonenumbers.siprouting.SipRoutingClientBuilder;
import com.azure.communication.phonenumbers.siprouting.models.SipTrunk;
import com.azure.communication.phonenumbers.siprouting.models.SipTrunkRoute;
import static java.util.Arrays.asList;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Direct Routing Quickstart");
        // Quickstart code goes here
    }
}

验证客户端

借助 SipRoutingClientBuilder，可使用 Microsoft Entra 身份验证：

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

SipRoutingAsyncClient sipRoutingAsyncClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

此外，还可使用来自通信资源的终结点和访问密钥进行身份验证：

// You can find your connection string from your resource in the Azure portal
String connectionString = "endpoint=https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<ACCESS_KEY>";

SipRoutingAsyncClient sipRoutingAsyncClient = new SipRoutingClientBuilder()
    .connectionString(connectionString)
    .buildClient();

设置直接路由配置

在先决条件中，你已验证域所有权。后续步骤是创建中继（添加 SBC）并创建语音路由。

创建或更新中继

Azure 通信服务直接路由仅允许与已注册的 SBC 通信。若要注册 SBC，需要其 FQDN 和端口：

sipRoutingAsyncClient.setTrunksWithResponse(asList(
	new SipTrunk("sbc.us.contoso.com", 5061),
	new SipTrunk("sbc.eu.contoso.com", 5061)
)).block();

创建或更新路由

为出站呼叫提供路由规则。每个规则由两部分组成：应匹配拨打的电话号码的正则表达式模式和路由呼叫的已注册中继的 FQDN。

路由顺序决定了路由的优先级。在呼叫时将选择与正则表达式匹配的第一个路由。

在此示例中，为以 +1 开头的号码创建一个路由，为仅以 + 开头的号码创建另一个路由：

sipRoutingAsyncClient.setRoutes(asList(
	new SipTrunkRoute("UsRoute", "^\\+1(\\d{10})$").setTrunks(asList("sbc.us.contoso.com")),
	new SipTrunkRoute("DefaultRoute", "^\\+\\d+$").setTrunks(asList("sbc.us.contoso.com", "sbc.eu.contoso.com"))
)).block();

更新直接路由配置

通过使用相同的 FQDN 覆盖记录，可更新特定中继的属性。例如，可以设置新的 SBC 端口值：

sipRoutingClient.setTrunk(new SipTrunk("sbc.us.contoso.com", 5063));

使用相同的方法创建和更新路由规则。更新路由时，在一次更新中发送所有路由。新的路由配置将完全覆盖以前的路由配置。

移除直接路由配置

无法编辑或移除单个语音路由。应覆盖整个语音路由配置。下面是移除所有路由和中继的空列表的示例。

添加两个导入：

import java.util.Collections;
import java.util.List;

使用以下代码删除直接路由配置：

//delete all configured voice routes
System.out.println("Delete all routes");
List<SipTrunkRoute> routes = Collections.<SipTrunkRoute> emptyList();
sipRoutingAsyncClient.setRoutes(routes).block();

//delete all trunks
System.out.println("Delete all trunks");
List<SipTrunk> trunks = Collections.<SipTrunk> emptyList();
sipRoutingAsyncClient.setTrunksWithResponse(trunks).block();

可以使用以下示例删除单个中继 (SBC)，前提是没有语音路由正在使用它。如果 SBC 在任何语音路由中列出，请先删除该路由。

sipRoutingClient.deleteTrunk("sbc.us.contoso.com");

运行代码

转到包含 pom.xml 文件的目录，并使用以下 mvn 命令编译该项目：

  mvn clean compile

然后生成包：

  mvn package

运行以下 mvn 命令来运行应用：

  mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
活动的通信服务资源和连接字符串。创建通信服务资源。
适用于你的操作系统的活动 LTS 版和维护 LTS 版 Node.js。
操作电话系统中会话边界控制器 (SBC) 的完全限定的域名 (FQDN) 和端口号。
SBC FQDN 的经验证的域名。

最终代码

在 GitHub 上查找此快速入门的最终代码。

还可在 GitHub 上找到更多 SipRoutingClient 的用法示例。

创建 Node.js 应用程序

打开终端或命令窗口，为应用创建一个新目录，并转到该目录：

    mkdir direct-routing-quickstart && cd direct-routing-quickstart

运行 npm init -y 以使用默认设置创建 package.json 文件：

   npm init -y

在创建的根目录中，创建一个名为 direct-routing-quickstart.js 的文件。将以下代码片段添加到此文件中：

async function main() {
    // quickstart code will go here
}

main();

安装包

使用 npm install 命令安装适用于 JavaScript 的 Azure 通信服务电话号码客户端库：

   npm install @azure/communication-phone-numbers --save

--save 选项将该库作为 package.json 文件中的依赖项列出。

验证客户端

从该客户端库导入 SipRoutingClient，并使用连接字符串将其实例化。该代码从名为 COMMUNICATION_SERVICES_CONNECTION_STRING 的环境变量中检索资源的连接字符串。了解如何管理资源的连接字符串。

将以下代码添加到 direct-routing-quickstart.js：

const { SipRoutingClient } = require('@azure/communication-phone-numbers');

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the phone numbers client
const sipRoutingClient = new SipRoutingClient(connectionString);

设置直接路由配置

在先决条件中，你已验证域所有权。后续步骤是创建中继（添加 SBC）并创建语音路由。

创建或更新中继

Azure 通信服务直接路由仅允许与已注册的 SBC 通信。若要注册 SBC，需要其 FQDN 和端口：

  await client.setTrunks([
    {
      fqdn: 'sbc.us.contoso.com',
      sipSignalingPort: 5061
    },{
      fqdn: 'sbc.eu.contoso.com',
      sipSignalingPort: 5061
    }
  ]);

创建或更新路由

为出站呼叫提供路由规则。每个规则由两部分组成：应匹配拨打的电话号码的正则表达式模式和路由呼叫的已注册中继的 FQDN。

路由顺序决定了路由的优先级。在呼叫时将选择与正则表达式匹配的第一个路由。

在此示例中，为以 +1 开头的号码创建一个路由，为仅以 + 开头的号码创建另一个路由：

   await client.setRoutes([
    {
      name: "UsRoute",
      description: "route's description",
      numberPattern: "^\+1(\d{10})$",
      trunks: [ 'sbc.us.contoso.com' ]
    },{
      name: "DefaultRoute",
      description: "route's description",
      numberPattern: "^\+\d+$",
      trunks: [ 'sbc.us.contoso.com', 'sbc.eu.contoso.com']
    }
  ]);

更新直接路由配置

通过使用相同的 FQDN 覆盖记录，可更新特定中继的属性。例如，可以设置新的 SBC 端口值：

  await client.setTrunk({
    fqdn: 'sbc.us.contoso.com',
    sipSignalingPort: 5063
  });

使用相同的方法创建和更新路由规则。更新路由时，在一次更新中发送所有路由。新的路由配置将完全覆盖以前的路由配置。

移除直接路由配置

无法编辑或移除单个语音路由。应覆盖整个语音路由配置。下面是移除所有路由和中继的空列表的示例：

//delete all configured voice routes
console.log("Deleting all routes...");
await client.setRoutes([]);

//delete all trunks
console.log("Deleting all trunks...");
await client.setTrunks([]);

可以使用以下示例删除单个中继 (SBC)，前提是没有语音路由正在使用它。如果 SBC 在任何语音路由中列出，请先删除该路由。

   await client.deleteTrunk('sbc.us.contoso.com');

运行代码

使用 node 命令运行添加到 direct-routing-quickstart.js 文件中的代码：

   node direct-routing-quickstart.js

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Python 3.7+。
已部署的通信服务资源和连接字符串。创建通信服务资源。
操作电话系统中会话边界控制器 (SBC) 的完全限定的域名 (FQDN) 和端口号。
SBC FQDN 的经验证的域名。

最终代码

在 GitHub 上查找此快速入门的最终代码。

还可在 GitHub 上找到更多 SipRoutingClient 的用法示例。

创建 Python 应用程序

打开终端或命令窗口。为应用创建新目录，然后转到该目录：

mkdir direct-routing-quickstart && cd direct-routing-quickstart

使用文本编辑器在项目根目录下创建名为 direct_routing_sample.py 的文件，然后添加以下代码：

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient, SipTrunk, SipTrunkRoute

try:
   print('Azure Communication Services - Direct Routing Quickstart')
   # Quickstart code goes here
except Exception as ex:
   print('Exception:')
   print(ex)

在以下各个部分中添加剩余的快速入门代码。

安装包

仍在应用程序目录中时，使用 pip install 命令安装适用于 Python 的 Azure 通信服务管理客户端库：

pip install azure-communication-phonenumbers==1.1.0

验证客户端

借助 SipRoutingClient，可使用 Microsoft Entra 身份验证。使用 DefaultAzureCredential 对象是开始使用 Microsoft Entra ID 的最简单方法，可以使用 pip install 命令安装它：

pip install azure-identity

创建 DefaultAzureCredential 对象要求你使用已注册 Microsoft Entra 应用程序中的对应值将 AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_TENANT_ID 设置为环境变量。有关获取这些环境变量的快速方法，请参阅使用 Microsoft Entra ID 进行身份验证。

安装 azure-identity 库后，可以继续对客户端进行身份验证：

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient
from azure.identity import DefaultAzureCredential

# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
    print('Azure Communication Services - Direct Routing Quickstart')
    credential = DefaultAzureCredential()
    sip_routing_client = SipRoutingClient(endpoint, credential)
except Exception as ex:
    print('Exception:')
    print(ex)

此外，还可以使用来自通信资源的终结点和访问密钥进行身份验证：

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient

# You can find your connection string from your resource in the Azure portal
connection_string = 'https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>'
try:
    print('Azure Communication Services - Direct Routing Quickstart')
    sip_routing_client = SipRoutingClient.from_connection_string(connection_string)
except Exception as ex:
    print('Exception:')
    print(ex)

设置直接路由配置

在先决条件中，你已验证域所有权。后续步骤是创建中继（添加 SBC）并创建语音路由。

创建或更新中继

通过提供 SBC 的完全限定的域名和端口号来注册 SBC：

new_trunks = [SipTrunk(fqdn="sbc.us.contoso.com", sip_signaling_port=1234), SipTrunk(fqdn="sbc.eu.contoso.com", sip_signaling_port=1234)]
sip_routing_client.set_trunks(new_trunks)

创建或更新路由

为出站呼叫提供路由规则。每个规则由两部分组成：应匹配拨打的电话号码的正则表达式模式和路由呼叫的已注册中继的 FQDN。

路由顺序决定了路由的优先级。在呼叫时将选择与正则表达式匹配的第一个路由。

在此示例中，为以 +1 开头的号码创建一个路由，为仅以 + 开头的号码创建另一个路由：

us_route = SipTrunkRoute(name="UsRoute", description="Handle US numbers '+1'", number_pattern="^\\+1(\\d{10})$", trunks=["sbc.us.contoso.com"])
def_route = SipTrunkRoute(name="DefaultRoute", description="Handle all numbers", number_pattern="^\\+\\d+$", trunks=["sbc.us.contoso.com","sbc.eu.contoso.com"])
new_routes = [us_route, def_route]
sip_routing_client.set_routes(new_routes)

更新直接路由配置

通过使用相同的 FQDN 覆盖记录，可更新特定中继的属性。例如，可以设置新的 SBC 端口值：

new_trunk = SipTrunk(fqdn="sbc.us.contoso.com", sip_signaling_port=5063)
sip_routing_client.set_trunk(new_trunk)

使用相同的方法创建和更新路由规则。更新路由时，在一次更新中发送所有路由。新的路由配置将完全覆盖以前的路由配置。

移除直接路由配置

无法编辑或移除单个语音路由。应覆盖整个语音路由配置。下面是移除所有路由和中继的空列表的示例：

#delete all configured voice routes
print('Deleting all routes...')
sip_routing_client.set_routes([])

#delete all trunks
print('Deleting all trunks...')
sip_routing_client.set_trunks([])

可以使用以下示例删除单个中继 (SBC)，前提是没有语音路由正在使用它。如果 SBC 在任何语音路由中列出，请先删除该路由。

sip_routing_client.delete_trunk("sbc.us.contoso.com")

运行代码

在控制台提示符下，转到包含 direct_routing_sample.py 文件的目录。然后，运行以下 Python 命令来运行应用：

python direct_routing_sample.py

清理资源

如果想要清理并删除通信服务订阅，可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。了解有关清理资源的详细信息。

后续步骤

有关详细信息，请参阅以下文章：

了解呼叫自动化，以生成路由和管理对通信服务的呼叫的工作流。
了解通话 SDK 的功能。
详细了解通话工作原理。
按照快速入门拨打电话号码。

通过

快速入门：以编程方式配置语音路由

先决条件

添加会话边界控制器

创建语音路由规则

移除直接路由配置

先决条件

最终代码

创建 C# 应用程序

安装包

验证客户端

设置直接路由配置

创建或更新中继

创建或更新路由

更新直接路由配置

移除直接路由配置

先决条件

最终代码

创建 Java 应用程序

安装包

设置应用框架

验证客户端

设置直接路由配置

创建或更新中继

创建或更新路由

更新直接路由配置

移除直接路由配置

运行代码

先决条件

最终代码

创建 Node.js 应用程序

安装包

验证客户端

设置直接路由配置

创建或更新中继

创建或更新路由

更新直接路由配置

移除直接路由配置

运行代码

先决条件

最终代码

创建 Python 应用程序

安装包

验证客户端

设置直接路由配置

创建或更新中继

创建或更新路由

更新直接路由配置

移除直接路由配置

运行代码

清理资源

后续步骤

反馈

其他资源