Libreria client del pacchetto numeri di telefono di Comunicazione di Azure per Python - versione 1.1.0

Articolo
03/30/2023

Il pacchetto client Numeri di comunicazione di Azure viene usato per amministrare i numeri di telefono.

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato 01 gennaio 2022. Per altre informazioni e domande, vedere https://github.com/Azure/azure-sdk-for-python/issues/20691

Introduzione

Prerequisiti

Python 3.7 o versione successiva è necessario per usare questo pacchetto.
È necessario disporre di una sottoscrizione di Azure
Una risorsa di Servizi di comunicazione distribuita. È possibile usare il portale di Azure o il Azure PowerShell per configurarlo.

Installare il pacchetto

Installare la libreria client Numeri di telefono di comunicazione di Azure per Python con pip:

pip install azure-communication-phonenumbers

Concetti chiave

Questo SDK offre funzionalità per gestire direct offer e direct routing numeri facilmente.

I direct offer numeri sono disponibili in due tipi: geografico e gratuito. I piani telefonici geografici sono piani telefonici associati a una posizione, i cui codici di area dei numeri di telefono sono associati al codice di area di una posizione geografica. Toll-Free piani telefonici sono piani telefonici non associati. Ad esempio, negli Stati Uniti, i numeri verdi possono venire con codici di area, ad esempio 800 o 888. Vengono gestiti usando PhoneNumbersClient

La direct routing funzionalità consente di connettere l'infrastruttura di telefonia esistente a ACS. La configurazione viene gestita usando SipRoutingClient, che fornisce metodi per configurare i trunk SIP e le regole di routing vocale, per gestire correttamente le chiamate per la subnet di telefonia.

Inizializzazione del client

È possibile inizializzare il client usando l'autenticazione 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())

Un'altra opzione consiste nell'inizializzare il client usando la stringa di connessione della risorsa.

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

Client numeri di telefono

Panoramica dei tipi di numero di telefono

I numeri di telefono sono disponibili in due tipi; Geografico e gratuito. I numeri di telefono geografici sono numeri di telefono associati a una posizione, i cui codici di area sono associati al codice di area di una posizione geografica. Toll-Free numeri di telefono sono numeri di telefono senza posizione associata. Ad esempio, negli Stati Uniti, i numeri verdi possono venire con codici di area, ad esempio 800 o 888.

Ricerca e acquisto e rilascio di numeri

I numeri di telefono possono essere cercati tramite l'API di creazione della ricerca fornendo un codice di area, una quantità di numeri di telefono, il tipo di applicazione, il tipo di numero di telefono e le funzionalità. La quantità fornita di numeri di telefono sarà riservata per dieci minuti e può essere acquistata entro questo periodo. Se la ricerca non viene acquistata, i numeri di telefono saranno disponibili per altri dopo dieci minuti. Se la ricerca viene acquistata, i numeri di telefono vengono acquisiti per le risorse di Azure.

I numeri di telefono possono essere rilasciati anche usando l'API di rilascio.

Client di routing SIP

La funzionalità di routing diretto consente di connettere l'infrastruttura di telefonia fornita dal cliente alle risorse di comunicazione di Azure. Per configurare correttamente la configurazione del routing, il cliente deve fornire la configurazione del trunk SIP e le regole di routing SIP per le chiamate. Il client di routing SIP fornisce l'interfaccia necessaria per impostare questa configurazione.

Quando viene eseguita una chiamata, il sistema tenta di corrispondere al numero di destinazione con modelli di numero regex di route definite. Verrà selezionata la prima route che corrisponde al numero. L'ordine di corrispondenza regex corrisponde all'ordine delle route nella configurazione, pertanto l'ordine delle route è importante. Dopo la corrispondenza di una route, la chiamata viene instradata al primo trunk nell'elenco dei trunk della route. Se il trunk non è disponibile, viene selezionato il trunk successivo nell'elenco.

Esempio

PhoneNumbersClient

Ottenere tutti i numeri di telefono acquistati

Elenca tutti i numeri di telefono acquistati

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

Ottenere il numero di telefono acquistato

Ottiene le informazioni dal numero di telefono specificato

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

Operazioni a esecuzione prolungata

Il client numero di telefono supporta un'ampia gamma di operazioni a esecuzione prolungata che consentono il polling indefinito alle funzioni elencate di seguito.

Cercare il numero di telefono disponibile

È possibile cercare numeri di telefono disponibili fornendo le funzionalità del telefono che si vuole acquisire, il tipo di numero di telefono, il tipo di assegnazione e il codice paese. Vale la pena ricordare che per il tipo di numero telefonico gratuito, dimostrando che il codice dell'area è facoltativo. Il risultato della ricerca può quindi essere usato per acquistare il numero nell'API corrispondente.

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

Acquistare numeri di telefono

Il risultato della ricerca può essere usato per acquistare i numeri di telefono specificati. Questa operazione può essere eseguita passando la search_id risposta dalla ricerca all'API numero di telefono di acquisto.

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

Numero di telefono rilascio

Rilascia un numero di telefono acquisito.

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

Aggiornamento delle funzionalità del numero di telefono

Aggiornamenti le funzionalità del numero di telefono specificato per chiamate e SMS a uno di:

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

Recuperare trunk e route SIP

Ottenere l'elenco di trunk o route attualmente configurati.

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)

Sostituire i trunk e le route SIP

Sostituire l'elenco di trunk o route attualmente configurati con nuovi valori.

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)

Recuperare un singolo trunk

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

Impostare un singolo trunk

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

Eliminare un singolo trunk

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

Risoluzione dei problemi

Il client Amministrazione numeri di telefono genererà eccezioni definite in Azure Core.

Passaggi successivi

Altro codice di esempio

Esaminare la directory degli esempi per esempi di come usare questa libreria.

Commenti e suggerimenti

Se si verificano bug o suggerimenti, segnalare un problema nella sezione Problemi del progetto

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Condividi tramite