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

适用于 .NET 的 Azure 通信电话号码客户端库 - 版本 1.1.0

项目
04/03/2023

Azure 通信电话号码管理Azure 通信服务的电话号码。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 通信电话号码客户端库：

dotnet add package Azure.Communication.PhoneNumbers

先决条件

需要一个 Azure 订阅和一个通信服务资源才能使用此包。

若要创建新的通信服务，可以使用 Azure 门户、Azure PowerShell或 .NET 管理客户端库。

关键概念

此 SDK 提供轻松管理和direct offerdirect routing编号的功能。

号码 direct offer 有两种类型：地理和免费电话。地理电话套餐是与某个位置关联的电话套餐，其电话号码的区号与地理位置的区号相关联。 Toll-Free电话套餐不是关联位置的电话计划。例如，在美国，免费电话号码可以附带区号，例如 800 或 888。它们使用 PhoneNumbersClient

此功能 direct routing 支持将现有电话基础结构连接到 ACS。配置使用 SipRoutingClient进行管理，该配置提供用于设置 SIP 中继和语音路由规则的方法，以便正确处理电话子网的呼叫。

验证客户端

可以使用从 Azure 门户中的 Azure 通信资源获取的连接字符串对客户端进行身份验证。

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

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

客户端还可以选择使用 Azure Active Directory 身份验证进行身份验证。有关本主题的详细信息，请参阅 Azure 标识。

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new SipRoutingClient(endpoint, tokenCredential);

电话号码客户端

电话号码类型概述

电话号码有两种类型：地理和免费电话号码。地理电话套餐是与某个位置关联的电话套餐，其电话号码的区号与地理位置的区号相关联。 Toll-Free电话套餐不是关联位置的电话计划。例如，在美国，免费电话号码可以附带区号，例如 800 或 888。

同一国家/地区中的所有地理电话计划都分组到具有地理电话号码类型的电话计划组中。同一国家/地区中的所有Toll-Free电话计划都分组到一个电话计划组中。

搜索、购买和发布电话号码

可以通过搜索创建 API 通过提供区号、电话号码数量、应用程序类型、电话号码类型和功能来搜索电话号码。提供的电话号码数量将保留 10 分钟，并可在这段时间内购买。如果未购买搜索，则电话号码将在十分钟后可供其他人使用。如果购买了搜索，则会获取 Azure 资源的电话号码。

还可以使用发布 API 发布电话号码。

SIP 路由客户端

直接路由功能允许将客户提供的电话基础结构连接到 Azure 通信资源。为了正确设置路由配置，客户需要为呼叫提供 SIP 中继配置和 SIP 路由规则。 SIP 路由客户端提供了设置此配置所需的接口。

进行调用时，系统会尝试将目标号码与已定义路由的正则表达式编号模式匹配。将选择与数字匹配的第一个路由。正则表达式匹配的顺序与配置中的路由顺序相同，因此路由顺序很重要。匹配路由后，呼叫将路由到路由中继列表中的第一个中继。如果中继不可用，则选择列表中的下一个中继。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立 (准则) 。这可确保重用客户端实例的建议始终是安全的，即使在线程之间也是如此。

其他概念

示例

PhoneNumbersClient

创建 PhoneNumbersClient

若要创建新的 PhoneNumbersClient ，需要一个Azure 通信服务资源的连接字符串，创建资源后，可以从 Azure 门户获取该字符串。

可以根据 connectionString 环境变量、配置设置或适用于应用程序的任何方式进行设置。

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

搜索电话号码

在购买电话号码之前，需要先搜索电话号码。搜索是一种长时间运行的操作，可由返回 SearchAvailablePhoneNumbersOperation 对象的函数启动StartSearchAvailablePhoneNumbers。 SearchAvailablePhoneNumbersOperation可用于更新操作的状态和检查完整性。

var capabilities = new PhoneNumberCapabilities(calling: PhoneNumberCapabilityType.None, sms: PhoneNumberCapabilityType.Outbound);

var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync(countryCode, PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities);
await searchOperation.WaitForCompletionAsync();

购买电话号码

可以通过购买搜索来获取电话号码。

var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();

列出购买的电话号码

可以列出为资源购买的所有电话号码。

var purchasedPhoneNumbers = client.GetPurchasedPhoneNumbersAsync();

await foreach (var phoneNumber in purchasedPhoneNumbers)
{
    Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}, monthly cost: {phoneNumber.Cost}");
}

释放电话号码

如果不再需要电话号码，可以释放它。

var purchasedPhoneNumber = "<purchased_phone_number>";
var releaseOperation = await client.StartReleasePhoneNumberAsync(purchasedPhoneNumber);
await releaseOperation.WaitForCompletionResponseAsync();
await WaitForCompletionResponseAsync(releaseOperation);

SipRoutingClient

检索 SIP 中继和路由

获取当前配置的中继或路由的列表。

var trunksResponse = await client.GetTrunksAsync();
var routesResponse = await client.GetRoutesAsync();

替换 SIP 中继和路由

替换当前配置的中继或路由的列表。

// The service will not allow trunks that are used in any of the routes to be deleted, therefore first set the routes as empty list, and then update the routes.
var newTrunks = "<new_trunks_list>";
var newRoutes = "<new_routes_list>";
await client.SetRoutesAsync(new List<SipTrunkRoute>());
await client.SetTrunksAsync(newTrunks);
await client.SetRoutesAsync(newRoutes);

管理单个中继

通过使用检索、设置或删除单个中继，可以单独 SipRoutingClient 管理 SIP 中继。

检索单个中继

// Get trunk object, based on it's FQDN.
var fqdnToRetrieve = "<fqdn>";
var trunkResponse = await client.GetTrunkAsync(fqdnToRetrieve);

设置单个中继

// Set function will either modify existing item or add new item to the collection.
// The trunk is matched based on it's FQDN.
var trunkToSet = "<trunk_to_set>";
await client.SetTrunkAsync(trunkToSet);

删除单个中继

// Deletes trunk with supplied FQDN.
var fqdnToDelete = "<fqdn>";
await client.DeleteTrunkAsync(fqdnToDelete);

疑难解答

后续步骤

详细了解如何管理电话号码

详细了解直接路由

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过