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

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

项目
03/30/2023

Azure 通信电话号码客户端包用于管理电话号码。

免责声明

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

入门

先决条件

使用此包需要 Python 3.7 或更高版本。
必须具有 Azure 订阅
已部署的通信服务资源。可以使用 Azure 门户或Azure PowerShell对其进行设置。

安装包

使用 pip 安装适用于 Python 的 Azure 通信电话号码客户端库：

pip install azure-communication-phonenumbers

关键概念

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

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

此功能 direct routing 支持将现有电话基础结构连接到 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)

电话号码客户端

电话号码类型概述

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

搜索、购买和发布号码

可以通过搜索创建 API 通过提供区号、电话号码数量、应用程序类型、电话号码类型和功能来搜索电话号码。提供的电话号码数量将保留 10 分钟，并可在这段时间内购买。如果未购买搜索，则电话号码将在 10 分钟后可供其他人使用。如果购买了搜索，则会获取 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 中定义的异常。

后续步骤

提供反馈

如果遇到任何 bug 或有建议，请在项目的“ 问题 ”部分中提出问题

贡献

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

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

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

通过