Клиентская библиотека пакета номеров телефонов для коммуникации Azure для Python версии 1.1.0

Статья
03/30/2023

Для администрирования номеров телефонов используется клиентский пакет номеров телефонов для связи Azure.

Заявление об отказе

Поддержка пакетов Python для Пакета Sdk Azure для Python 2.7 закончилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Предварительные требования

Для использования этого пакета требуется Python 3.7 или более поздней версии.
У вас должна быть подписка Azure.
Развернутый ресурс Служб коммуникации. Для настройки можно использовать портал Azure или Azure PowerShell.

Установка пакета

Установите клиентную библиотеку номеров телефонов связи Azure для Python с помощью pip:

pip install azure-communication-phonenumbers

Основные понятия

Этот пакет SDK предоставляет функциональные возможности для легкого управления числами direct offer и direct 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 создания поиска, указав код региона, количество номеров телефонов, тип приложения, тип номера телефона и возможности. Указанное количество номеров телефонов будет зарезервировано на десять минут и может быть приобретено в течение этого времени. Если поиск не был приобретен, номера телефонов станут доступны другим пользователям через десять минут. Если поиск приобретен, для ресурсов 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
)

Обновление возможностей номера телефона

Обновления указанные возможности телефонного номера для звонков и SMS на один из следующих способов:

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.

Дальнейшие действия

Больше примеров кода

Подробные примеры использования этой библиотеки см. в каталоге примеров .

Отзывы

Если вы столкнулись с ошибками или у вас есть предложения, сообщите о проблеме в разделе Проблемы проекта.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Поделиться через