Biblioteca de cliente do Pacote de Números de Telefone do Azure Communication para Python – versão 1.1.0

Artigo
03/30/2023

O pacote de cliente Números de Telefone do Azure Communication é utilizado para administrar Números de Telefone.

Exclusão de Responsabilidade

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

Introdução

Pré-requisitos

O Python 3.7 ou posterior é necessário para utilizar este pacote.
Tem de ter uma subscrição do Azure
Um recurso do Communication Services implementado. Pode utilizar o Portal do Azure ou o Azure PowerShell para configurá-lo.

Instalar o pacote

Instale a biblioteca de cliente Azure Communication Phone Numbers para Python com pip:

pip install azure-communication-phonenumbers

Conceitos-chave

Este SDK fornece funcionalidades para gerir direct offerdirect routing e números facilmente.

Os direct offer números são apresentados em dois tipos: Geográfico e Gratuito. Os planos de telefone geográficos são planos de telefone associados a uma localização, 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 que não estão associados à localização. Por exemplo, nos EUA, os números gratuitos podem ser fornecidos com códigos de área como 800 ou 888. São geridos com o PhoneNumbersClient

A direct routing funcionalidade permite ligar a sua infraestrutura de telefonia existente ao ACS. A configuração é gerida com o SipRoutingClient, que fornece métodos para configurar ramais SIP e regras de encaminhamento de voz, de modo a processar corretamente chamadas para a sua sub-rede de telefonia.

A inicializar o Cliente

O cliente pode ser inicializado com 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 com a cadeia de ligaçã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

Descrição geral dos tipos de número de telefone

Os números de telefone são apresentados em dois tipos; Geográfico e gratuito. Os números de telefone geográficos são números de telefone associados a uma localização, 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, os números gratuitos podem ser fornecidos com códigos de área como 800 ou 888.

Procurar e Comprar e Libertar números

Os números de telefone podem ser pesquisados através da API de criação de pesquisa ao fornecer um código de área, quantidade de números de telefone, tipo de aplicação, tipo de número de telefone e capacidades. A quantidade fornecida de números de telefone será reservada durante dez minutos e poderá ser comprada dentro deste período de tempo. 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 são adquiridos para os recursos do Azure.

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

Cliente de encaminhamento SIP

A funcionalidade de encaminhamento direto permite ligar a infraestrutura de telefonia fornecida pelo cliente aos Recursos de Comunicação do Azure. Para configurar corretamente a configuração de encaminhamento, o cliente tem de fornecer a configuração do ramal SIP e as regras de encaminhamento SIP para chamadas. O cliente de encaminhamento SIP fornece a interface necessária para definir esta configuração.

Quando uma chamada é efetuada, o sistema tenta corresponder o número de destino com padrões de número regex de rotas definidas. Será selecionada a primeira rota para corresponder ao número. A ordem da correspondência de regex é a mesma que a ordem das rotas na configuração, pelo que a ordem das rotas é importante. Assim que uma rota for correspondida, a chamada é encaminhada para o primeiro ramal na lista de ramais da rota. Se o ramal não estiver disponível, o próximo ramal na lista está selecionado.

Exemplos

PhoneNumbersClient

Obter Todos os Números de Telefone Comprados

Lista todos os 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 suporta uma variedade de operações de execução prolongada que permitem tempo de consulta indefinido para as funções listadas abaixo.

Procurar Número de Telefone Disponível

Pode procurar números de telefone disponíveis ao fornecer as capacidades do telefone que pretende adquirir, o tipo de número de telefone, o tipo de atribuição e o código de país/região. Vale a pena mencionar que, para o tipo de número de telefone gratuito, provar que o código de área é opcional. O resultado da pesquisa pode ser utilizado 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 utilizado para comprar os números de telefone especificados. Isto pode ser feito ao transmitir a search_id partir 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
)

Número de Telefone da Versão

Liberta um número de telefone adquirido.

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

A atualizar capacidades de número de telefone

Atualizações as capacidades de número de telefone especificadas para Chamadas e SMS para uma das 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

Obter ramais e rotas SIP

Obtenha a lista de ramais ou rotas atualmente configurados.

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 ramais e rotas SIP

Substitua a lista de ramais ou rotas atualmente configurados 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)

Obter um único tronco

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

Definir ramal ú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 ramal único

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

Resolução de problemas

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

Passos seguintes

Mais código de exemplo

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Enviar Comentários

Se encontrar erros ou tiver sugestões, submeta um problema na secção Problemas do projeto

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Partilhar via