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

Artigo
04/03/2023

Os Números de Telefone de Comunicação do Azure estão gerenciando números de telefone para Serviços de Comunicação do Azure.

Código-fonte | Documentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes de Números de Telefone de Comunicação do Azure para .NET com o NuGet:

dotnet add package Azure.Communication.PhoneNumbers

Pré-requisitos

Você precisa de uma assinatura do Azure e um Recurso do Serviço de Comunicação para usar esse pacote.

Para criar um novo Serviço de Comunicação, você pode usar o Portal do Azure, o Azure PowerShell ou a biblioteca de clientes de gerenciamento do .NET.

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.

Autenticar o cliente

Os clientes podem ser autenticados usando a cadeia de conexão adquirida de um Recurso de Comunicação do Azure no Portal do Azure.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);

// Get a connection string to Azure Communication resource.
var connectionString = "<connection_string>";
var client = new SipRoutingClient(connectionString);

Os clientes também têm a opção de autenticar com a Autenticação do Azure Active Directory. Para obter mais informações sobre este tópico, consulte Identidade do Azure.

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new SipRoutingClient(endpoint, tokenCredential);

Cliente de números de telefone

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

Os números de telefone 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.

Todos os planos telefônicos geográficos no mesmo país são agrupados em um grupo de planos telefônicos com um tipo de número de telefone Geográfico. Todos os Toll-Free planos telefônicos dentro do mesmo país são agrupados em um grupo de planos telefônicos.

Pesquisando, comprando e liberando números de telefone

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.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

PhoneNumbersClient

Criando um PhoneNumbersClient

Para criar um novoPhoneNumbersClient, você precisa de uma cadeia de conexão para o recurso Serviços de Comunicação do Azure que você pode obter no Portal do Azure depois de criar o recurso.

Você pode definir connectionString com base em uma variável de ambiente, uma configuração ou qualquer maneira que funcione para seu aplicativo.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);

Pesquisar números de telefone

Os números de telefone precisam ser pesquisados antes de serem comprados. A pesquisa é uma operação de execução prolongada que pode ser iniciada pela StartSearchAvailablePhoneNumbers função que retorna um SearchAvailablePhoneNumbersOperation objeto . SearchAvailablePhoneNumbersOperationpode ser usado para atualizar status da operação e para marcar para fins de integridade.

var capabilities = new PhoneNumberCapabilities(calling: PhoneNumberCapabilityType.None, sms: PhoneNumberCapabilityType.Outbound);

var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync(countryCode, PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities);
await searchOperation.WaitForCompletionAsync();

Comprar números de telefone

Os números de telefone podem ser adquiridos por meio da compra de uma pesquisa.

var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();

Listando números de telefone comprados

Você pode listar todos os números de telefone que foram comprados para o recurso.

var purchasedPhoneNumbers = client.GetPurchasedPhoneNumbersAsync();

await foreach (var phoneNumber in purchasedPhoneNumbers)
{
    Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}, monthly cost: {phoneNumber.Cost}");
}

Liberar números de telefone

Se você não precisar mais de um número de telefone, poderá liberá-lo.

var purchasedPhoneNumber = "<purchased_phone_number>";
var releaseOperation = await client.StartReleasePhoneNumberAsync(purchasedPhoneNumber);
await releaseOperation.WaitForCompletionResponseAsync();
await WaitForCompletionResponseAsync(releaseOperation);

SipRoutingClient

Recuperar troncos e rotas SIP

Obtenha a lista de troncos ou rotas configurados no momento.

var trunksResponse = await client.GetTrunksAsync();
var routesResponse = await client.GetRoutesAsync();

Substituir troncos SIP e rotas

Substitua a lista de troncos ou rotas configurados no momento.

// The service will not allow trunks that are used in any of the routes to be deleted, therefore first set the routes as empty list, and then update the routes.
var newTrunks = "<new_trunks_list>";
var newRoutes = "<new_routes_list>";
await client.SetRoutesAsync(new List<SipTrunkRoute>());
await client.SetTrunksAsync(newTrunks);
await client.SetRoutesAsync(newRoutes);

Gerenciar tronco único

Os troncos SIP podem ser gerenciados separadamente usando o SipRoutingClient para recuperar, definir ou excluir um único tronco.

Recuperar tronco único

// Get trunk object, based on it's FQDN.
var fqdnToRetrieve = "<fqdn>";
var trunkResponse = await client.GetTrunkAsync(fqdnToRetrieve);

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.
var trunkToSet = "<trunk_to_set>";
await client.SetTrunkAsync(trunkToSet);

Excluir tronco único

// Deletes trunk with supplied FQDN.
var fqdnToDelete = "<fqdn>";
await client.DeleteTrunkAsync(fqdnToDelete);

Solução de problemas

Próximas etapas

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 cla.microsoft.com.

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