Biblioteca de clientes do Pacote de Números de Telefone de Comunicação do Azure para Python – versão 1.1.0

Artigo
03/30/2023

O pacote de cliente números de telefone de comunicação do Azure é usado para administrar números de telefone.

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e tirar dúvidas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

É necessário ter o Python 3.7 ou posterior para usar esse pacote.
Você deve ter uma assinatura do Azure
Um recurso dos Serviços de Comunicação implantado. Você pode usar o Portal do Azure ou o Azure PowerShell para configurá-lo.

Instalar o pacote

Instale a biblioteca de clientes de Números de Telefone de Comunicação do Azure para Python com pip:

pip install azure-communication-phonenumbers

Principais conceitos

Esse SDK fornece funcionalidade para gerenciar direct offer e direct routing números com facilidade.

Os direct offer números vêm em dois tipos: Geográfico e Gratuito. Planos telefônicos geográficos são planos telefônicos associados a um local, cujos códigos de área de números de telefone estão associados ao código de área de uma localização geográfica. Toll-Free planos telefônicos são planos telefônicos não associados ao local. Por exemplo, nos EUA, números de chamada gratuita podem vir com códigos de área como 800 ou 888. Eles são gerenciados usando o PhoneNumbersClient

O direct routing recurso permite conectar sua infraestrutura de telefonia existente ao ACS. A configuração é gerenciada usando o SipRoutingClient, que fornece métodos para configurar troncos SIP e regras de roteamento de voz, a fim de lidar corretamente com chamadas para sua sub-rede de telefonia.

Inicializando o cliente

O cliente pode ser inicializado usando a autenticação do 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())

Outra opção é inicializar o cliente usando a cadeia de conexão do 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 telefone

Visão geral dos tipos de número de telefone

Números de telefone vêm em dois tipos; Geográfico e Gratuito. Números de telefone geográficos são números de telefone associados a um local, cujos códigos de área estão associados ao código de área de uma localização geográfica. Toll-Free números de telefone são números de telefone sem localização associada. Por exemplo, nos EUA, números de chamada gratuita podem vir com códigos de área como 800 ou 888.

Pesquisando e comprando e liberando números

Os números de telefone podem ser pesquisados por meio da API de criação de pesquisa fornecendo um código de área, quantidade de números de telefone, tipo de aplicativo, tipo de número de telefone e recursos. A quantidade fornecida de números de telefone será reservada por dez minutos e poderá ser adquirida dentro desse período. Se a pesquisa não for comprada, os números de telefone ficarão disponíveis para outras pessoas após dez minutos. Se a pesquisa for comprada, os números de telefone serão adquiridos para os recursos do Azure.

Os números de telefone também podem ser liberados usando a API de lançamento.

Cliente de roteamento SIP

O recurso de roteamento direto permite conectar a infraestrutura de telefonia fornecida pelo cliente aos Recursos de Comunicação do Azure. Para configurar a configuração de roteamento corretamente, o cliente precisa fornecer a configuração do tronco SIP e as regras de roteamento SIP para chamadas. O cliente de roteamento SIP fornece a interface necessária para definir essa configuração.

Quando uma chamada é feita, o sistema tenta corresponder o número de destino com padrões de número regex de rotas definidas. A primeira rota para corresponder ao número será selecionada. A ordem de correspondência de regex é a mesma que a ordem das rotas na configuração, portanto, a ordem das rotas importa. Depois que uma rota é correspondida, a chamada é roteada para o primeiro tronco na lista de troncos da rota. Se o tronco não estiver disponível, o próximo tronco na lista será selecionado.

Exemplos

PhoneNumbersClient

Obter todos os números de telefone comprados

Lista todos os seus números de telefone 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)

Obter número de telefone comprado

Obtém as informações do número de telefone especificado

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

Operações de execução prolongada

O Cliente de Número de Telefone dá suporte a uma variedade de operações de execução prolongada que permitem tempo de sondagem indefinido para as funções listadas abaixo.

Pesquisar número de telefone disponível

Você pode pesquisar números de telefone disponíveis fornecendo os recursos do telefone que deseja adquirir, o tipo de número de telefone, o tipo de atribuição e o código do país. Vale mencionar que, para o tipo de número de telefone de chamada gratuita, é possível provar que o código de área é opcional. O resultado da pesquisa pode ser usado para comprar o número na API correspondente.

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

Comprar números de telefone

O resultado da pesquisa pode ser usado para comprar os números de telefone especificados. Isso pode ser feito passando o search_id da resposta de pesquisa para a API de número de telefone de compra.

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

Liberar número de telefone

Libera um número de telefone adquirido.

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

Atualizando recursos de número de telefone

Atualizações os recursos de número de telefone especificados para Chamada e SMS para um dos seguintes:

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

Recuperar troncos e rotas SIP

Obtenha a lista de troncos ou rotas configurados no momento.

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)

Substituir troncos SIP e rotas

Substitua a lista de troncos ou rotas configurados no momento por novos 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)

Recuperar tronco único

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

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

Excluir tronco único

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

Solução de problemas

O cliente de Administração de Números de Telefone gerará exceções definidas no Azure Core.

Próximas etapas

Mais códigos de exemplo

Dê uma olhada no diretório de exemplos para obter exemplos detalhados de como usar essa biblioteca.

Forneça comentários

Se você encontrar bugs ou tiver sugestões, registre um problema na seção Problemas do projeto

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Compartilhar via