Klientská knihovna balíčků telefonních čísel služby Azure Communication pro Python – verze 1.1.0

Článek
03/30/2023

Klientský balíček telefonních čísel služby Azure Communication slouží ke správě telefonních čísel.

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Požadavky

K použití tohoto balíčku se vyžaduje Python 3.7 nebo novější.
Musíte mít předplatné Azure.
Nasazený prostředek Komunikační služby K jeho nastavení můžete použít Azure Portal nebo Azure PowerShell.

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Communication Phone Numbers pro Python pomocí pipu:

pip install azure-communication-phonenumbers

Klíčové koncepty

Tato sada SDK poskytuje funkce pro snadnou správu direct offer čísel a direct routing čísel.

Čísla direct offer jsou ve dvou typech: zeměpisné a bezplatné. Zeměpisné telefonní tarify jsou telefonní tarify spojené s místem, jehož směrová čísla jsou přidružená k směrovým kódům oblasti zeměpisného umístění. Toll-Free telefonní tarify jsou telefonní tarify, které nejsou přidružené místo. Například v USA můžou bezplatná čísla obsahovat směrová čísla oblastí 800 nebo 888. Spravují se pomocí PhoneNumbersClient

Tato direct routing funkce umožňuje připojit stávající telefonní infrastrukturu ke službě ACS. Konfigurace se spravuje pomocí SipRoutingClientnástroje , který poskytuje metody pro nastavení kmenů PROTOKOLU SIP a pravidel směrování hlasu, aby bylo možné správně zpracovat volání pro vaši telefonní podsíť.

Inicializace klienta

Klienta je možné inicializovat pomocí ověřování 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())

Další možností je inicializovat klienta pomocí připojovacího řetězce prostředku.

# 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 telefonních čísel

Přehled typů telefonních čísel

Telefonní čísla mají dva typy; Geografická a bezplatná linka. Zeměpisná telefonní čísla jsou telefonní čísla přidružená k místu, jehož směrová čísla oblastí jsou přidružená k směrovým kódům oblasti zeměpisné polohy. Toll-Free telefonní čísla jsou telefonní čísla bez přidružené polohy. Například v USA můžou bezplatná čísla obsahovat směrová čísla oblastí 800 nebo 888.

Vyhledávací a nákupní a uvolňovací čísla

Telefonní čísla je možné prohledávat prostřednictvím rozhraní API pro vytváření vyhledávání tak, že zadáte směrové číslo oblasti, množství telefonních čísel, typ aplikace, typ telefonního čísla a možnosti. Zadané množství telefonních čísel bude rezervováno na deset minut a během této doby je možné je zakoupit. Pokud hledání není zakoupeno, telefonní čísla budou po deseti minutách dostupná ostatním uživatelům. Pokud je vyhledávání koupené, telefonní čísla se pořídí pro prostředky Azure.

Telefonní čísla je také možné vydat pomocí rozhraní API verze.

Klient směrování SIP

Funkce přímého směrování umožňuje připojit telefonní infrastrukturu poskytovanou zákazníkem ke komunikačním prostředkům Azure. Aby zákazník správně nastavil konfiguraci směrování, musí pro volání zadat konfiguraci kmene SIP a pravidla směrování SIP. Klient směrování SIP poskytuje potřebné rozhraní pro nastavení této konfigurace.

Při volání se systém pokusí spárovat cílové číslo se vzory čísel regex definovaných tras. Vybere se první trasa, která bude odpovídat číslu. Pořadí porovnávání regulárních výrazů je stejné jako pořadí tras v konfiguraci, proto na pořadí tras záleží. Po spárování trasy se hovor přesměruje do prvního kmene v seznamu kmenů trasy. Pokud kufr není k dispozici, vybere se další kmen v seznamu.

Příklady

PhoneNumbersClient

Získat všechna zakoupená telefonní čísla

Zobrazí seznam všech zakoupených telefonních čísel.

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

Získat zakoupené telefonní číslo

Získá informace ze zadaného telefonního čísla.

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

Dlouhotrvající operace

Klient telefonního čísla podporuje řadu dlouhotrvajících operací, které umožňují neomezenou dobu dotazování na níže uvedené funkce.

Vyhledání dostupného telefonního čísla

Dostupná telefonní čísla můžete vyhledat tak, že zadáte možnosti telefonu, který chcete získat, typ telefonního čísla, typ přiřazení a směrové číslo země. Za zmínku stojí, že pro typ bezplatného telefonního čísla je nepovinné prokázat směrové číslo oblasti. Výsledek hledání pak můžete použít k nákupu čísla v příslušném rozhraní 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()

Nákup telefonních čísel

Výsledek hledání můžete použít k nákupu zadaných telefonních čísel. To lze provést předáním search_id odpovědi z hledání do rozhraní API telefonního čísla nákupu.

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

Telefonní číslo verze

Uvolní získané telefonní číslo.

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

Aktualizace funkcí telefonních čísel

Aktualizace zadané telefonní číslo pro volání a SMS na jednu z těchto možností:

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

Načtení kmenů a tras SIP

Získejte seznam aktuálně nakonfigurovaných kmenů nebo 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)

Výměna kmenů a tras SIP

Nahraďte seznam aktuálně nakonfigurovaných kmenů nebo tras novými hodnotami.

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)

Načtení jednoho kmene

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

Nastavit jeden kufr

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

Odstranit jeden kmen

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

Řešení potíží

Klient správy telefonních čísel vyvolá výjimky definované v Azure Core.

Další kroky

Další ukázkový kód

Podrobné příklady použití této knihovny najdete v adresáři samples .

Zadání zpětné vazby

Pokud narazíte na nějaké chyby nebo máte návrhy, zapište problém v části Problémy projektu.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Sdílet prostřednictvím