Biblioteca de clientes de Números de Telefone de Comunicação do Azure para Java – versão 1.1.7

Artigo
10/25/2023

O pacote de números de telefone fornece recursos para o gerenciamento de números de telefone.

Os números de telefone comprados podem vir com muitas funcionalidades, dependendo do país, do tipo de número e do plano telefônico. Exemplos de recursos são o uso de entrada e saída de SMS, chamando o uso de entrada e saída. Os números de telefone também podem ser atribuídos a um bot por meio de uma URL de webhook.

Código-fonte | Pacote (Maven) | Documentação | de referência da API Documentação do produto

Introdução

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
JDK (Java Development Kit) versão 8 ou superior.
Apache Maven.
Um recurso dos Serviços de Comunicação implantado. Você pode usar o Portal do Azure ou o Azure PowerShell para configurá-lo.

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-phonenumbers</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente na BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-phonenumbers</artifactId>
  <version>1.1.7</version>
</dependency>

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. Os 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

Os clientes podem ser inicializados usando a Autenticação do Azure Active Directory.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

O uso do ponto de extremidade e da chave de acesso do recurso de comunicação para autenticação também é possível.

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

Como alternativa, você pode fornecer toda a cadeia de conexão usando a função connectionString() do cliente em vez de fornecer o ponto de extremidade e a chave de acesso.

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. Os 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.

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 comprados 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 a chamada chega, 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 número de telefone comprado

Obtém o número de telefone comprado especificado.

PurchasedPhoneNumber phoneNumber = phoneNumberClient.getPurchasedPhoneNumber("+18001234567");
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

Obter todos os números de telefone comprados

Lista todos os números de telefone comprados.

PagedIterable<PurchasedPhoneNumber> phoneNumbers = createPhoneNumberClient().listPurchasedPhoneNumbers(Context.NONE);
PurchasedPhoneNumber phoneNumber = phoneNumbers.iterator().next();
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

Operações de execução prolongada

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

Pesquisar números de telefone disponíveis

Pesquise números de telefone disponíveis fornecendo o código de área, o tipo de atribuição, os recursos de número de telefone, o tipo de número de telefone e a quantidade. O resultado da pesquisa pode ser usado para comprar os números. Observe que para números de telefone do tipo chamada gratuita, fornecer o código de área é opcional.

PhoneNumbersClient phoneNumberClient = createPhoneNumberClient();
PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities()
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);
PhoneNumberSearchOptions searchOptions = new PhoneNumberSearchOptions().setAreaCode("800").setQuantity(1);

SyncPoller<PhoneNumberOperation, PhoneNumberSearchResult> poller = phoneNumberClient
    .beginSearchAvailablePhoneNumbers("US", PhoneNumberType.TOLL_FREE, PhoneNumberAssignmentType.APPLICATION, capabilities, searchOptions, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();
String searchId = "";

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PhoneNumberSearchResult searchResult = poller.getFinalResult();
    searchId = searchResult.getSearchId();
    System.out.println("Searched phone numbers: " + searchResult.getPhoneNumbers());
    System.out.println("Search expires by: " + searchResult.getSearchExpiresBy());
    System.out.println("Phone number costs:" + searchResult.getCost().getAmount());
}

Comprar números de telefone

O resultado da pesquisa por números de telefone é um PhoneNumberSearchResult. Isso pode ser usado para obter os detalhes dos números e os números de compra passando para searchId a API do número de compra.

PollResponse<PhoneNumberOperation> purchaseResponse =
    phoneNumberClient.beginPurchasePhoneNumbers(searchId, Context.NONE).waitForCompletion();
System.out.println("Purchase phone numbers is complete: " + purchaseResponse.getStatus());

Liberar número de telefone

Libera um número de telefone comprado.

PollResponse<PhoneNumberOperation> releaseResponse =
    phoneNumberClient.beginReleasePhoneNumber("+18001234567", Context.NONE).waitForCompletion();
System.out.println("Release phone number is complete: " + releaseResponse.getStatus());

Atualizando recursos de número de telefone

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

PhoneNumberCapabilityValue.NONE
PhoneNumberCapabilityValue.INBOUND
PhoneNumberCapabilityValue.OUTBOUND
PhoneNumberCapabilityValue.INBOUND_OUTBOUND

PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities();
capabilities
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);

SyncPoller<PhoneNumberOperation, PurchasedPhoneNumber> poller = phoneNumberClient.beginUpdatePhoneNumberCapabilities("+18001234567", capabilities, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PurchasedPhoneNumber phoneNumber = poller.getFinalResult();
    System.out.println("Phone Number Calling capabilities: " + phoneNumber.getCapabilities().getCalling()); //Phone Number Calling capabilities: inbound
    System.out.println("Phone Number SMS capabilities: " + phoneNumber.getCapabilities().getSms()); //Phone Number SMS capabilities: inbound+outbound
}

SipRoutingClient

Recuperar troncos e rotas SIP

Obtenha a lista de troncos ou rotas configurados no momento.

PagedIterable<SipTrunk> trunks = sipRoutingClient.listTrunks();
PagedIterable<SipTrunkRoute> routes = sipRoutingClient.listRoutes();
for (SipTrunk trunk : trunks) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
}
for (SipTrunkRoute route : routes) {
    System.out.println("Route name: " + route.getName());
    System.out.println("Route description: " + route.getDescription());
    System.out.println("Route number pattern: " + route.getNumberPattern());
    System.out.println("Route trunks: " + String.join(",", route.getTrunks()));
}

Substituir troncos SIP e rotas

Substitua a lista de troncos ou rotas configurados no momento por novos valores.

sipRoutingClient.setTrunks(asList(
    new SipTrunk("<first trunk fqdn>", 12345),
    new SipTrunk("<second trunk fqdn>", 23456)
));
sipRoutingClient.setRoutes(asList(
    new SipTrunkRoute("route name1", ".*9").setTrunks(asList("<first trunk fqdn>", "<second trunk fqdn>")),
    new SipTrunkRoute("route name2", ".*").setTrunks(asList("<second trunk fqdn>"))
));

Recuperar tronco único

String fqdn = "<trunk fqdn>";
SipTrunk trunk = sipRoutingClient.getTrunk(fqdn);
if (trunk != null) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
} else {
    System.out.println("Trunk not found. " + fqdn);
}

Definir tronco único

sipRoutingClient.setTrunk(new SipTrunk("<trunk fqdn>", 12345));

Excluir tronco único

sipRoutingClient.deleteTrunk("<trunk fqdn>");

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.

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.

Solução de problemas

Em andamento.

Próximas etapas

Confira outras bibliotecas de clientes para o serviço de comunicação do Azure

Impressões

Compartilhar via