Biblioteca cliente del paquete de números de teléfono de Comunicación de Azure para Python: versión 1.1.0

Artículo
03/30/2023

El paquete de cliente números de teléfono de comunicación de Azure se usa para administrar números de teléfono.

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Requisitos previos

Se requiere Python 3.7 o posterior para usar este paquete.
Debe tener una suscripción de Azure.
Un recurso de Communication Services implementado. Puede usar Azure Portal o el Azure PowerShell para configurarlo.

Instalar el paquete

Instale la biblioteca cliente de números de teléfono de comunicación de Azure para Python con pip:

pip install azure-communication-phonenumbers

Conceptos clave

Este SDK proporciona funcionalidad para administrar direct offer y direct routing números fácilmente.

Los direct offer números vienen en dos tipos: geográfico y gratuito. Los planes telefónicos geográficos son planes de teléfono asociados a una ubicación, cuyos códigos de área de números de teléfono están asociados con el código de área de una ubicación geográfica. Toll-Free planes de teléfono son planes de teléfono no asociados. Por ejemplo, en estados Unidos, los números gratuitos pueden tener códigos de área como 800 o 888. Se administran mediante PhoneNumbersClient

La direct routing característica permite conectar la infraestructura de telefonía existente a ACS. La configuración se administra mediante , SipRoutingClientque proporciona métodos para configurar troncos SIP y reglas de enrutamiento de voz, con el fin de controlar correctamente las llamadas de la subred de telefonía.

Inicialización del cliente

El cliente se puede inicializar mediante la autenticación de 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())

Otra opción es inicializar el cliente mediante la cadena de conexión del recurso.

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

Cliente de números de teléfono

Introducción a los tipos de números de teléfono

Los números de teléfono vienen en dos tipos; Geográfico y gratuito. Los números de teléfono geográficos son números de teléfono asociados a una ubicación, cuyos códigos de área están asociados al código de área de una ubicación geográfica. Toll-Free números de teléfono son números de teléfono sin ubicación asociada. Por ejemplo, en estados Unidos, los números gratuitos pueden tener códigos de área como 800 o 888.

Buscar y comprar y liberar números

Los números de teléfono se pueden buscar a través de la API de creación de búsquedas proporcionando un código de área, cantidad de números de teléfono, tipo de aplicación, tipo de número de teléfono y funcionalidades. La cantidad proporcionada de números de teléfono se reservará durante diez minutos y se podrá comprar en este momento. Si no se compra la búsqueda, los números de teléfono estarán disponibles para otros después de diez minutos. Si se compra la búsqueda, los números de teléfono se adquieren para los recursos de Azure.

Los números de teléfono también se pueden publicar mediante la API de versión.

Cliente de enrutamiento SIP

La característica de enrutamiento directo permite conectar la infraestructura de telefonía proporcionada por el cliente a los recursos de comunicación de Azure. Para configurar correctamente la configuración de enrutamiento, el cliente debe proporcionar la configuración del tronco SIP y las reglas de enrutamiento SIP para las llamadas. El cliente de enrutamiento SIP proporciona la interfaz necesaria para establecer esta configuración.

Cuando se realiza una llamada, el sistema intenta hacer coincidir el número de destino con patrones de número regex de rutas definidas. Se seleccionará la primera ruta para que coincida con el número. El orden de coincidencia de expresiones regulares es el mismo que el orden de las rutas en la configuración, por lo que el orden de las rutas importa. Una vez que se coincide con una ruta, la llamada se enruta al primer tronco de la lista de troncos de la ruta. Si el tronco no está disponible, se selecciona el siguiente tronco de la lista.

Ejemplos

PhoneNumbersClient

Obtener todos los números de teléfono comprados

Enumera todos los números de teléfono comprados

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

Obtener número de teléfono comprado

Obtiene la información del número de teléfono especificado.

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

Operaciones de larga duración

El cliente de número de teléfono admite una variedad de operaciones de larga duración que permiten el tiempo de sondeo indefinido a las funciones enumeradas a continuación.

Buscar número de teléfono disponible

Puede buscar números de teléfono disponibles proporcionando las funcionalidades del teléfono que desea adquirir, el tipo de número de teléfono, el tipo de asignación y el código de país. Merece la pena mencionar que, para el tipo de número de teléfono gratuito, demostrar que el código de área es opcional. El resultado de la búsqueda se puede usar para comprar el número en la API correspondiente.

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

Compra de números de teléfono

El resultado de la búsqueda se puede usar para comprar los números de teléfono especificados. Para ello, pase la search_id respuesta de búsqueda a la API de número de teléfono de compra.

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

Liberación de números de teléfono

Libera un número de teléfono adquirido.

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

Actualizar las funcionalidades del número de teléfono

Novedades las funcionalidades de número de teléfono especificadas para llamadas y SMS a uno de:

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

Recuperación de troncos SIP y rutas

Obtenga la lista de troncos o rutas configurados actualmente.

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)

Reemplazar troncos SIP y rutas

Reemplace la lista de troncos o rutas configurados actualmente por nuevos valores.

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)

Recuperación de tronco único

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

Establecer tronco único

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

Eliminar tronco único

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

Solución de problemas

El cliente de administración de números de teléfono generará excepciones definidas en Azure Core.

Pasos siguientes

Más código de ejemplo

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados de cómo usar esta biblioteca.

Envío de comentarios

Si encuentra algún error o tiene sugerencias, envíe un problema en la sección Problemas del proyecto.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Compartir a través de