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

适用于 Java 的 Azure 通信电话号码客户端库 - 版本 1.1.7

项目
10/25/2023

电话号码包提供电话号码管理功能。

购买的电话号码可以附带许多功能，具体取决于国家/地区、号码类型和电话计划。功能的示例包括短信入站和出站使用情况、调用入站和出站使用情况。还可以通过 Webhook URL 将电话号码分配给机器人。

源代码 | 包 (Maven) | API 参考文档 | 产品文档

入门

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Java 开发工具包 (JDK) 8 或更高版本。
Apache Maven。
已部署的通信服务资源。可以使用 Azure 门户或Azure PowerShell进行设置。

添加包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的正式发布 (GA) 版本。在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后在没有版本标记的依赖项部分中包含直接依赖项。

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

包括直接依赖项

如果要依赖于 BOM 中不存在的特定版本的库，请将直接依赖项添加到项目中，如下所示。

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

关键概念

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

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

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

初始化客户端

可以使用 Azure Active Directory 身份验证初始化客户端。

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

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

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

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

还可以使用通信资源的终结点和访问密钥进行身份验证。

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

或者，可以使用客户端的 connectionString () 函数来提供整个连接字符串，而不是提供终结点和访问密钥。

电话号码客户端

电话号码类型概述

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

搜索、购买和释放号码

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

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

SIP 路由客户端

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

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

示例

PhoneNumbersClient

获取购买的电话号码

获取指定的购买电话号码。

PurchasedPhoneNumber phoneNumber = phoneNumberClient.getPurchasedPhoneNumber("+18001234567");
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

获取所有购买的电话号码

列出所有购买的电话号码。

PagedIterable<PurchasedPhoneNumber> phoneNumbers = createPhoneNumberClient().listPurchasedPhoneNumbers(Context.NONE);
PurchasedPhoneNumber phoneNumber = phoneNumbers.iterator().next();
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

长时间运行的操作

电话号码客户端支持各种长时间运行的操作，这些操作允许对下面列出的函数无限期轮询。

搜索可用的电话号码

通过提供区号、分配类型、电话号码功能、电话号码类型和数量来搜索可用的电话号码。然后，可以使用搜索结果来购买号码。请注意，对于免费电话号码类型，可以选择是否提供区号。

PhoneNumbersClient phoneNumberClient = createPhoneNumberClient();
PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities()
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);
PhoneNumberSearchOptions searchOptions = new PhoneNumberSearchOptions().setAreaCode("800").setQuantity(1);

SyncPoller<PhoneNumberOperation, PhoneNumberSearchResult> poller = phoneNumberClient
    .beginSearchAvailablePhoneNumbers("US", PhoneNumberType.TOLL_FREE, PhoneNumberAssignmentType.APPLICATION, capabilities, searchOptions, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();
String searchId = "";

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PhoneNumberSearchResult searchResult = poller.getFinalResult();
    searchId = searchResult.getSearchId();
    System.out.println("Searched phone numbers: " + searchResult.getPhoneNumbers());
    System.out.println("Search expires by: " + searchResult.getSearchExpiresBy());
    System.out.println("Phone number costs:" + searchResult.getCost().getAmount());
}

购买电话号码

电话号码的搜索结果是 PhoneNumberSearchResult 条。这可以通过将传递到 searchId 购买编号 API 来获取号码的详细信息和购买编号。

PollResponse<PhoneNumberOperation> purchaseResponse =
    phoneNumberClient.beginPurchasePhoneNumbers(searchId, Context.NONE).waitForCompletion();
System.out.println("Purchase phone numbers is complete: " + purchaseResponse.getStatus());

发布电话号码

释放购买的电话号码。

PollResponse<PhoneNumberOperation> releaseResponse =
    phoneNumberClient.beginReleasePhoneNumber("+18001234567", Context.NONE).waitForCompletion();
System.out.println("Release phone number is complete: " + releaseResponse.getStatus());

更新电话号码功能

汇报呼叫和短信的电话号码功能之一：

PhoneNumberCapabilityValue.NONE
PhoneNumberCapabilityValue.INBOUND
PhoneNumberCapabilityValue.OUTBOUND
PhoneNumberCapabilityValue.INBOUND_OUTBOUND

PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities();
capabilities
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);

SyncPoller<PhoneNumberOperation, PurchasedPhoneNumber> poller = phoneNumberClient.beginUpdatePhoneNumberCapabilities("+18001234567", capabilities, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PurchasedPhoneNumber phoneNumber = poller.getFinalResult();
    System.out.println("Phone Number Calling capabilities: " + phoneNumber.getCapabilities().getCalling()); //Phone Number Calling capabilities: inbound
    System.out.println("Phone Number SMS capabilities: " + phoneNumber.getCapabilities().getSms()); //Phone Number SMS capabilities: inbound+outbound
}

SipRoutingClient

检索 SIP 中继和路由

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

PagedIterable<SipTrunk> trunks = sipRoutingClient.listTrunks();
PagedIterable<SipTrunkRoute> routes = sipRoutingClient.listRoutes();
for (SipTrunk trunk : trunks) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
}
for (SipTrunkRoute route : routes) {
    System.out.println("Route name: " + route.getName());
    System.out.println("Route description: " + route.getDescription());
    System.out.println("Route number pattern: " + route.getNumberPattern());
    System.out.println("Route trunks: " + String.join(",", route.getTrunks()));
}

替换 SIP 中继和路由

将当前配置的中继或路由的列表替换为新值。

sipRoutingClient.setTrunks(asList(
    new SipTrunk("<first trunk fqdn>", 12345),
    new SipTrunk("<second trunk fqdn>", 23456)
));
sipRoutingClient.setRoutes(asList(
    new SipTrunkRoute("route name1", ".*9").setTrunks(asList("<first trunk fqdn>", "<second trunk fqdn>")),
    new SipTrunkRoute("route name2", ".*").setTrunks(asList("<second trunk fqdn>"))
));

检索单个中继

String fqdn = "<trunk fqdn>";
SipTrunk trunk = sipRoutingClient.getTrunk(fqdn);
if (trunk != null) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
} else {
    System.out.println("Trunk not found. " + fqdn);
}

设置单个中继

sipRoutingClient.setTrunk(new SipTrunk("<trunk fqdn>", 12345));

删除单个中继

sipRoutingClient.deleteTrunk("<trunk fqdn>");

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

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

疑难解答

In progress。

后续步骤

查看 Azure 通信服务的其他客户端库

曝光数

通过