Azure Communication Phone Numbers Package客户端库，用于Python

Azure Communication Phone Numbers客户端包用于管理电话号码。

免责声明

Azure SDK Python包对Python 2.7的支持已于2022年1月1日结束。有关更多信息及疑问，请参阅https://github.com/Azure/azure-sdk-for-python/issues/20691

入门

先决条件

• 要使用此包，需要Python 3.7或更高版本。
• 您必须拥有Azure订阅
• 已部署的Communication Services资源。您可以使用Azure Portal或Azure PowerShell来设置。

安装包

使用pip安装Azure Communication Phone Numbers客户端库

pip install azure-communication-phonenumbers

关键概念

本SDK提供功能，可轻松管理直接报价和直接路由电话号码。

直接报价电话号码分为两种类型：地理电话号码和免费电话号码。地理电话计划是与位置相关的电话计划，其电话号码的区号与地理位置的区号相关联。免费电话计划与位置无关。例如，在美国，免费电话号码可能带有800或888这样的区号。它们使用PhoneNumbersClient进行管理。

直接路由功能使您可以将现有的电话基础设施连接到ACS。配置使用SipRoutingClient进行管理，它提供了设置SIP中继线和语音路由规则的方法，以便正确处理电话子网中的电话。

初始化客户端

可以使用AAD身份验证初始化客户端。

import os
from azure.communication.phonenumbers import PhoneNumbersClient
from azure.identity import DefaultAzureCredential

endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
phone_numbers_client = PhoneNumbersClient(endpoint, DefaultAzureCredential())

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

endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
sip_routing_client = SipRoutingClient(endpoint, DefaultAzureCredential())

另一种选项是使用资源的连接字符串初始化客户端。

# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers import PhoneNumbersClient

connection_str = "endpoint=ENDPOINT;accessKey=KEY"
phone_numbers_client = PhoneNumbersClient.from_connection_string(connection_str)

# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient

connection_str = "endpoint=ENDPOINT;accessKey=KEY"
sip_routing_client = SipRoutingClient.from_connection_string(connection_str)

电话号码客户端

电话号码类型概述

电话号码分为两种；地理电话号码和免费电话号码。地理电话号码是与位置相关的电话号码，其区号与地理位置的区号相关联。免费电话号码是没有关联位置的电话号码。例如，在美国，免费电话号码可能带有800或888这样的区号。

搜索、购买和释放号码

可以通过提供区号、电话号码数量、应用程序类型、电话号码类型和功能来通过搜索创建API搜索电话号码。提供的电话号码数量将在十分钟内保留，并且可以在十分钟内购买。如果搜索未购买，电话号码将在十分钟之后对其他人开放。如果搜索已购买，则电话号码将用于Azure资源。

也可以使用释放API释放电话号码。

SIP路由客户端

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

当发起电话时，系统会尝试将目的地号码与已定义路由的正则表达式号码模式进行匹配。首先匹配的路由将被选中。正则表达式的匹配顺序与配置中路由的顺序相同，因此路由顺序很重要。一旦匹配到路由，电话将被路由到路由的中继线列表中的第一个中继线。如果中继线不可用，则选择列表中的下一个中继线。

示例

PhoneNumbersClient

获取所有购买的电话号码

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

purchased_phone_numbers = phone_numbers_client.list_purchased_phone_numbers()
for acquired_phone_number in purchased_phone_numbers:
    print(acquired_phone_number.phone_number)

获取购买的电话号码

从指定的电话号码获取信息

result = phone_numbers_client.get_purchased_phone_number("<phone number>")
print(result.country_code)
print(result.phone_number)

长时间运行的操作

电话号码客户端支持各种长时间运行的操作，允许对以下列出的函数进行不定期的轮询。

搜索可用的电话号码

您可以通过提供要获取的电话的功能、电话号码类型、分配类型和国家代码来搜索可用的电话号码。值得一提的是，对于免费电话号码类型，提供区号是可选的。搜索的结果可以用于在相应的API中购买号码。

capabilities = PhoneNumberCapabilities(
        calling = PhoneNumberCapabilityType.INBOUND,
        sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
    )
poller = phone_numbers_client.begin_search_available_phone_numbers(
    "US",
    PhoneNumberType.TOLL_FREE,
    PhoneNumberAssignmentType.APPLICATION,
    capabilities,
    area_code ="833", # Area code is optional for toll-free numbers
    quantity = 2, # Quantity is optional. If not set, default is 1
    polling = True
)
search_result = poller.result()

购买电话号码

搜索的结果可以用于购买指定的电话号码。这可以通过将搜索响应中的search_id传递到购买电话号码API来实现。

purchase_poller = phone_numbers_client.begin_purchase_phone_numbers(
    search_result.search_id,
    polling=True
)

释放电话号码

释放已获取的电话号码。

poller = self.phone_number_client.begin_release_phone_number(
    "<phone number>",
    polling = True
)

更新电话号码功能

更新指定的电话号码功能以进行通话和短信到以下之一

• PhoneNumberCapabilityType.NONE
• PhoneNumberCapabilityType.INBOUND
• PhoneNumberCapabilityType.OUTBOUND
• PhoneNumberCapabilityType.INBOUND_OUTBOUND

poller = self.phone_number_client.begin_update_phone_number_capabilities(
    "<phone number>",
    PhoneNumberCapabilityType.OUTBOUND,
    PhoneNumberCapabilityType.INBOUND_OUTBOUND,
    polling = True
)

SipRoutingClient

检索SIP中继和路由

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

trunks = sip_routing_client.list_trunks()
for trunk in trunks:
    print(trunk.fqdn)
    print(trunk.sip_signaling_port)
routes = sip_routing_client.list_routes()
for route in routes:
    print(route.name)
    print(route.description)
    print(route.number_pattern)
    for trunk_fqdn in route.trunks:
        print(trunk_fqdn)

替换SIP中继和路由

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

new_trunks = [SipTrunk(fqdn="sbs1.contoso.com", sip_signaling_port=1122), SipTrunk(fqdn="sbs2.contoso.com", sip_signaling_port=1123)]
new_routes = [SipTrunkRoute(name="First rule", description="Handle numbers starting with '+123'", number_pattern="\+123[0-9]+", trunks=["sbs1.sipconfigtest.com"])]
sip_routing_client.set_trunks(new_trunks)
sip_routing_client.set_routes(new_routes)

检索单个中继

trunk = sip_routing_client.get_trunk("sbs1.contoso.com")

设置单个中继

# Set function will either modify existing item or add new item to the collection.
# The trunk is matched based on it's FQDN.
new_trunk = SipTrunk(fqdn="sbs3.contoso.com", sip_signaling_port=5555)
sip_routing_client.set_trunk(new_trunk)

删除单个中继

sip_routing_client.delete_trunk("sbs1.contoso.com")

故障排除

电话号码管理客户端将引发在Azure Core中定义的异常。

下一步

更多示例代码

请参阅samples目录以获取如何使用此库的详细示例。

提供反馈

如果您遇到任何错误或有任何建议，请在项目的问题部分提交问题。

贡献

此项目欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议（CLA），声明您有权并且实际上授予我们使用您的贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

在您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并适当修饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您在整个使用我们的CLA的仓库中只需要这样做一次。

此项目采用了Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题解答或通过opencode@microsoft.com联系以获取任何额外的问题或评论。