Biblioteka klienta pakietu numerów telefonów usługi Azure Communication dla języka Python — wersja 1.1.0

Artykuł
03/30/2023

Pakiet klienta numerów telefonów usługi Azure Communication służy do administrowania numerami telefonów.

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python dla zestawu Azure SDK dla języka Python 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Wprowadzenie

Wymagania wstępne

Do korzystania z tego pakietu jest wymagany język Python w wersji 3.7 lub nowszej.
Musisz mieć subskrypcję platformy Azure
Wdrożony zasób usług Komunikacyjnych. Możesz użyć witryny Azure Portal lub Azure PowerShell, aby ją skonfigurować.

Instalowanie pakietu

Zainstaluj bibliotekę klienta numerów telefonów usługi Azure Communication dla języka Python za pomocą narzędzia pip:

pip install azure-communication-phonenumbers

Kluczowe pojęcia

Ten zestaw SDK udostępnia funkcje umożliwiające łatwe zarządzanie numerami i direct routing ich numeramidirect offer.

Liczby direct offer są dostępne w dwóch typach: Geograficzny i Bezpłatny. Geograficzne plany telefoniczne są planami telefonów skojarzonymi z lokalizacją, której numery telefonów są skojarzone z kodem kierunkowym lokalizacji geograficznej. Toll-Free plany telefoniczne to plany telefoniczne, które nie są skojarzone z lokalizacją. Na przykład w Stanach Zjednoczonych numery bezpłatne mogą być dostarczane z kodami obszarów, takimi jak 800 lub 888. Są one zarządzane przy użyciu narzędzia PhoneNumbersClient

Funkcja direct routing umożliwia łączenie istniejącej infrastruktury telefonii z usługą ACS. Konfiguracja jest zarządzana przy użyciu programu SipRoutingClient, który udostępnia metody konfigurowania magistrali SIP i reguł routingu głosowego, aby prawidłowo obsługiwać wywołania podsieci telefonii.

Inicjowanie klienta

Klienta można zainicjować przy użyciu uwierzytelniania usługi 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())

Inną opcją jest zainicjowanie klienta przy użyciu parametrów połączenia zasobu.

# 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)

Klient numerów telefonów

Omówienie typów numerów telefonów

Numery telefonów są dostępne w dwóch typach; Geograficzne i bezpłatne. Geograficzne numery telefonów to numery telefonów skojarzone z lokalizacją, której kody obszarów są skojarzone z kodem obszaru lokalizacji geograficznej. Toll-Free numerami telefonów są numery telefonów bez skojarzonej lokalizacji. Na przykład w Stanach Zjednoczonych numery bezpłatne mogą być dostarczane z kodami obszarów, takimi jak 800 lub 888.

Wyszukiwanie i kupowanie i zwalnianie liczb

Numery telefonów można przeszukiwać za pomocą interfejsu API tworzenia wyszukiwania, podając numer kierunkowy, liczbę numerów telefonów, typ aplikacji, typ numeru telefonu i możliwości. Podana ilość numerów telefonów będzie zarezerwowana przez dziesięć minut i może zostać zakupiona w tym czasie. Jeśli wyszukiwanie nie zostanie zakupione, numery telefonów staną się dostępne dla innych osób po dziesięciu minutach. Jeśli wyszukiwanie zostanie zakupione, numery telefonów zostaną uzyskane dla zasobów platformy Azure.

Numery telefonów można również zwolnić przy użyciu interfejsu API wydania.

Klient routingu SIP

Funkcja routingu bezpośredniego umożliwia łączenie infrastruktury telefonicznej dostarczonej przez klienta z zasobami usługi Azure Communication. Aby prawidłowo skonfigurować konfigurację routingu, klient musi podać konfigurację magistrali SIP i reguły routingu SIP dla połączeń. Klient routingu SIP udostępnia interfejs niezbędny do ustawienia tej konfiguracji.

Po wywołaniu system próbuje dopasować numer docelowy do wzorców liczb wyrażeń regularnych zdefiniowanych tras. Zostanie wybrana pierwsza trasa zgodna z liczbą. Kolejność dopasowywania wyrażeń regularnych jest taka sama jak kolejność tras w konfiguracji, dlatego kolejność tras ma znaczenie. Po dopasowaniu trasy połączenie jest kierowane do pierwszego magistrali na liście magistrali trasy. Jeśli magistrala jest niedostępna, zostanie wybrana następna magistrala na liście.

Przykłady

PhoneNumbersClient

Pobierz wszystkie zakupione numery telefonów

Wyświetla listę wszystkich zakupionych numerów telefonów

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

Uzyskiwanie zakupionego numeru telefonu

Pobiera informacje z określonego numeru telefonu

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

Długotrwałe operacje

Klient numeru telefonu obsługuje różne długotrwałe operacje, które umożliwiają nieokreślony czas sondowania dla funkcji wymienionych poniżej.

Wyszukaj dostępny numer telefonu

Możesz wyszukać dostępne numery telefonów, udostępniając możliwości telefonu, które chcesz uzyskać, typ numeru telefonu, typ przypisania i kod kraju. Warto wspomnieć, że w przypadku typu numeru telefonu bez opłat okazuje się, że numer kierunkowy jest opcjonalny. Wynik wyszukiwania może następnie służyć do zakupu numeru w odpowiednim interfejsie 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()

Kupowanie numerów telefonów

Wynik wyszukiwania może służyć do zakupu określonych numerów telefonów. Można to zrobić, przekazując element search_id z odpowiedzi wyszukiwania na interfejs API zakupu numeru telefonu.

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

Numer telefonu wydania

Zwalnia uzyskany numer telefonu.

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

Aktualizowanie możliwości numeru telefonu

Aktualizacje określone możliwości numeru telefonu dla połączeń telefonicznych i wiadomości SMS do jednego z:

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

Pobieranie magistrali SIP i tras

Pobierz listę aktualnie skonfigurowanych magistrali lub tras.

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)

Wymiana magistrali SIP i tras

Zastąp listę aktualnie skonfigurowanych magistrali lub tras nowymi wartościami.

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)

Pobieranie pojedynczego magistrali

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

Ustawianie pojedynczego bagażnika

# 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)

Usuwanie pojedynczego magistrali

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

Rozwiązywanie problemów

Klient Administracji numerami telefonów zgłosi wyjątki zdefiniowane w usłudze Azure Core.

Następne kroki

Więcej przykładów kodu

Zapoznaj się z katalogiem samples , aby zapoznać się ze szczegółowymi przykładami korzystania z tej biblioteki.

Przekazywanie opinii

Jeśli napotkasz jakiekolwiek usterki lub masz sugestie, zgłoś problem w sekcji Problemy w projekcie

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Udostępnij za pośrednictwem