Biblioteca de cliente 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 a gerir números de telefone para Azure Communication Services.

Código fonte | Documentação do | produto Exemplos

Introdução

Instalar o pacote

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

dotnet add package Azure.Communication.PhoneNumbers

Pré-requisitos

Precisa de uma subscrição do Azure e de um Recurso do Serviço de Comunicação para utilizar este pacote.

Para criar um novo Serviço de Comunicação, pode utilizar o Portal do Azure, o Azure PowerShell ou a biblioteca de cliente de gestão .NET.

Conceitos-chave

Este SDK fornece funcionalidades para gerir direct offer e direct routing 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 nã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 calções SIP e regras de encaminhamento de voz, de modo a processar corretamente as chamadas para a sua sub-rede de telefonia.

Autenticar o cliente

Os clientes podem ser autenticados através da cadeia de ligação adquirida a partir de recursos 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, veja 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

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 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 não associados à localização. Por exemplo, nos EUA, os números gratuitos podem ser fornecidos com códigos de área como 800 ou 888.

Todos os planos de telefone geográfico no mesmo país estão agrupados num grupo de planos telefónicos com um tipo de número de telefone Geográfico. Todos os Toll-Free planos telefónicos no mesmo país estão agrupados num grupo de planos telefónicos.

Procurar, comprar e libertar números de telefone

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 versão.

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 as regras de configuração do tronco do SIP e 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 regex é igual à 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 tronco na lista de troncos da rota. Se o porta-malas não estiver disponível, o próximo porta-malas na lista está selecionado.

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

PhoneNumbersClient

Criar um PhoneNumbersClient

Para criar um novoPhoneNumbersClient, precisa de uma cadeia de ligação para o recurso Azure Communication Services que pode obter a partir do Portal do Azure depois de criar o recurso.

Pode definir connectionString com base numa variável de ambiente, numa definição de configuração ou em qualquer forma que funcione para a sua aplicação.

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

Procurar números de telefone

Os números de telefone têm de ser procurados antes de poderem ser comprados. A pesquisa é uma operação de execução prolongada que pode ser iniciada por StartSearchAvailablePhoneNumbers função que devolve um SearchAvailablePhoneNumbersOperation objeto. SearchAvailablePhoneNumbersOperation pode ser utilizado para atualizar o estado da operação e para verificar a conclusão.

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 através da compra de uma pesquisa.

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

Listar números de telefone comprados

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}");
}

Libertar números de telefone

Se já não precisar de um número de telefone, pode lançá-lo.

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

SipRoutingClient

Obter porta-malas e rotas SIP

Obtenha a lista de trajetos ou rotas atualmente configurados.

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

Substituir os porta-malas e rotas do SIP

Substitua a lista de trajetos ou rotas atualmente configurados.

// 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);

Gerir um único tronco

Os troncos SIP podem ser geridos separadamente ao utilizar o SipRoutingClient para obter, definir ou eliminar um único tronco.

Obter um único tronco

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

Definir um único tronco

// 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);

Eliminar um único tronco

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

Resolução de problemas

Passos seguintes

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 obter detalhes, visite cla.microsoft.com.

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 o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.