Início Rápido: Obter e gerenciar números de telefone
Importante
Os recursos de SMS e PSTN dependem do número de telefone que você usa e do país/região no qual você está operando, conforme determinado pelo seu endereço de cobrança do Azure. Para saber mais, acesse a documentação Qualificação para assinatura.
Importante
Para pedidos de alto volume ou caso o número de telefone desejado não esteja disponível, visite esta página para obter mais assistência.
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Um recurso ativo dos Serviços de Comunicação.
Obter um número de telefone
Para começar a provisionar números, vá até seu recurso dos Serviços de Comunicação no portal do Azure.
Pesquisar números de telefone disponíveis
Acesse a folha Números de Telefone no menu de recursos.
Clique no botão Obter para iniciar o assistente. O assistente na folha Números de telefone orientará você em uma série de perguntas que ajudarão a escolher o número de telefone mais adequado para seu cenário.
Primeiro, você precisará escolher o País/região em que deseja provisionar o número de telefone. Depois de selecionar o País/a região, você precisará escolher o Caso de uso mais adequado às suas necessidades.
Selecionar os recursos de número de telefone
A configuração do número de telefone é dividida em duas etapas:
- A seleção do tipo de número
- A seleção das funcionalidades de número
Você pode selecionar um de dois tipos de números de telefone: Local e Chamada gratuita. Quando selecionar um tipo de número, escolha o recurso.
Em nosso exemplo, selecionamos o tipo de número Chamada gratuita com os recursos Fazer chamadas e Enviar e receber SMS.
Aqui, clique no botão Avançar: Números na parte inferior da página para personalizar os números de telefone que deseja provisionar.
Personalizando números de telefone
Na página Números, você personalizará os números de telefone que deseja provisionar.
Observação
Este guia de início rápido mostra o fluxo de personalização do Tipo de número Chamada gratuita. A experiência poderá ser ligeiramente diferente se você tiver escolhido o tipo de número Local, mas o resultado final será o mesmo.
Escolha o Código de área na lista de Códigos de área disponíveis, insira a quantidade que deseja provisionar e clique em Pesquisar para encontrar números que atendam aos requisitos selecionados. Os números de telefone que atenderem às suas necessidades serão mostrados, bem como seu custo mensal.
Observação
A disponibilidade depende do Tipo de número, da localização e dos recursos selecionados. Os números ficam reservados por um período curto antes que a transação expire. Se a transação expirar, você precisará selecionar os números novamente.
Para ver o resumo da compra e fazer seu pedido, clique no botão Avançar: Resumo na parte inferior da página.
Comprar números de telefone
A página de resumo trará uma revisão com o Tipo de número, os Recursos, os Números de telefone e o Custo mensal total para provisionar os números de telefone.
Observação
Os preços mostrados são os encargos mensais recorrentes, que cobrem o custo de cessão do número de telefone selecionado a você. Nessa exibição, não estão incluídos os Custos pagos conforme o uso, que são cobrados quando você faz ou recebe chamadas. As listas de preços estão disponíveis aqui. Esses custos dependem do tipo de número e dos destinos das chamadas. Por exemplo, o preço por minuto de uma chamada de um número regional de Seattle para um número regional de Nova York e de uma chamada do mesmo número para um número de celular do Reino Unido poderão ser diferentes.
Por fim, clique em Fazer pedido na parte inferior da página para confirmá-lo.
Localizar seus números de telefone no portal do Azure
Navegue até seu recurso dos Serviços de Comunicação do Azure no portal do Azure:
Selecione a folha Números de Telefone no menu para gerenciar seus números de telefone.
Observação
Poderão ser necessários alguns minutos para que os números provisionados sejam mostrados nesta página.
Atualizar as funcionalidades do número de telefone
Na página Números de telefone, você poderá selecionar um número de telefone para configurá-lo.
Selecione os recursos entre as opções disponíveis e clique em Salvar para aplicar a seleção.
Liberar número de telefone
Na página Números, você pode liberar números de telefone.
Selecione o número de telefone que deseja liberar e clique no botão Liberar.
Importante
Este recurso dos Serviços de Comunicação do Azure estão atualmente em versão prévia.
Versões prévias das APIs e dos SDKs são fornecidas sem um contrato de nível de serviço. É recomendável que você não as use para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou talvez ter restrição de recursos.
Para saber mais, consulte os Termos de Uso Complementares das Versões Prévias do Microsoft Azure.
Os Serviços de Comunicação do Azure estão introduzindo uma nova experiência do usuário para comprar números de telefone. Essa experiência está sendo disponibilizada na versão piloto no momento e você pode ter acesso ao comprar um número de telefone no portal do Azure. Se você tiver comentários sobre essa experiência, não hesite em fornecer pelo botão Fornecer comentários na extensão do portal do Azure.
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Um recurso ativo dos Serviços de Comunicação.
Comprar um número de telefone
Navegue até o recurso do Serviço de Comunicação no portal do Azure.
Na visão geral do recurso dos Serviços de Comunicação, selecione na opção "Números de telefone" no menu à esquerda.
Selecione Obter no canto superior esquerdo da página para comprar seu número de telefone. Ao selecionar isso, o assistente de compras será inicializado:
Escolha o País/região em que deseja provisionar o número de telefone. A disponibilidade do país/região é baseada no local de cobrança de sua assinatura do Azure. Mais informações sobre quais números estão disponíveis para cada país/região podem ser encontradas aqui. Em seguida, você escolherá o tipo de número. Você pode selecionar um de dois tipos de números de telefone: Local e Chamada gratuita.
Selecione Pesquisar para efetuar pull de números que atendam aos critérios selecionados. Você tem vários filtros para pesquisar o número que atende às suas necessidades, incluindo:
- Caso de uso: para saber se você está usando esse número para chamada de um aplicativo (A2P) ou de um agente humano (P2P).
- Chamada: para determinar os recursos de Chamada que você deseja para o seu número de telefone: fazer chamadas e/ou receber chamadas.
- SMS: para determinar os recursos de SMS que você deseja para o seu número de telefone: enviar e/ou receber mensagens SMS.
- Personalizado: você também pode adicionar filtros personalizados para obter um determinado prefixo ou um conjunto de dígitos em seu número de telefone.
Depois de encontrar o número de telefone ou os números à sua escolha, selecione Adicionar ao carrinho para manter os números no carrinho de Telefonia. Esses números são mantidos por 16 minutos antes que o carrinho seja limpo automaticamente.
Observação
Os preços mostrados são os encargos mensais recorrentes, que cobrem o custo de cessão do número de telefone selecionado a você. Nessa exibição, não estão incluídos os Custos pagos conforme o uso, que são cobrados quando você faz ou recebe chamadas. As listas de preços estão disponíveis aqui. Esses custos dependem do tipo de número e dos destinos das chamadas. Por exemplo, o preço por minuto de uma chamada de um número regional de Seattle para um número regional de Nova York e de uma chamada do mesmo número para um número de celular do Reino Unido poderão ser diferentes.
Selecione Avançar para revisar sua aquisição. Para concluir a aquisição, selecione Comprar agora.
Você pode encontrar seus números adquiridos novamente na página Números de telefone. Pode levar alguns minutos para que os números sejam provisionados.
Atualizar as funcionalidades do número de telefone
Na página Números de telefone, você poderá selecionar um número de telefone para configurá-lo.
Selecione os recursos entre as opções disponíveis e selecione Salvar para aplicar a seleção.
Liberar número de telefone
Na página Números, você pode liberar números de telefone.
Selecione o número de telefone que deseja liberar e selecione o botão Liberar.
Pré-requisitos
Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Um recurso e uma cadeia de conexão ativos dos Serviços de Comunicação. Crie um recurso dos Serviços de Comunicação.
Instale a CLI do Azure.
Um número de telefone comprado.
Configurando
Adicionar a extensão
Adicione a extensão dos Serviços de Comunicação do Azure para a CLI do Azure usando o comando az extension.
az extension add --name communication
Entrar na CLI do Azure
Você precisará entrar na CLI do Azure. Para se conectar, execute o comando az login no terminal e forneça suas credenciais.
Operations
Lista de números de telefone comprados
Execute o comando a seguir para recuperar todos os números de telefone comprados.
az communication phonenumber list --connection-string "<yourConnectionString>"
Faça essa substituição no código:
- Substitua
<yourConnectionString>pela cadeia de conexão.
Obter detalhes dos números de telefone comprados
Execute o comando a seguir para obter os detalhes do número de telefone de um número de telefone comprado.
az communication phonenumber show --phonenumber <purchasedPhoneNumber> --connection-string "<yourConnectionString>"
Faça estas substituições no código:
- Substitua
<purchasedPhoneNumber>por um número de telefone associado ao recurso dos Serviços de Comunicação. - Substitua
<yourConnectionString>pela cadeia de conexão.
Observação
A opção Azure CLI fornece funcionalidade apenas para listar e mostrar números de telefone. Não oferece suporte a outras operações como pesquisa, compra, edição ou liberação de números de telefone.
(Opcional) Usar operações de números de telefone da CLI do Azure sem passar uma cadeia de conexão
Você pode configurar a variável de ambiente AZURE_COMMUNICATION_CONNECTION_STRING para usar números de telefone da CLI do Azure sem precisar usar --connection_string para passar a cadeia de conexão. Para configurar uma variável de ambiente, abra uma janela do console e selecione o sistema operacional nas guias abaixo. Substitua <yourConnectionString> pela cadeia de conexão real.
Abra uma janela do console e insira o seguinte comando:
setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"
Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se estiver usando o Visual Studio como seu editor, reinicie-o antes de executar o exemplo.
Observação
Encontre o código finalizado para este guia de início rápido no GitHub
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- A versão mais recente da biblioteca de clientes do .NET Core para o seu sistema operacional.
- Um recurso e uma cadeia de conexão ativos dos Serviços de Comunicação. Crie um recurso dos Serviços de Comunicação.
Verificação de pré-requisitos
- Em um terminal ou janela de comando, execute o comando
dotnetpara verificar se a biblioteca de clientes do .NET está instalada.
Configurando
Criar um aplicativo em C#
Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome PhoneNumbersQuickstart. Esse comando cria um projeto simples C# "Olá, Mundo" com um arquivo de origem único: Program.cs.
dotnet new console -o PhoneNumbersQuickstart
Altere o seu diretório para a pasta de aplicativo recém-criada e use o comando dotnet build para compilar o seu aplicativo.
cd PhoneNumbersQuickstart
dotnet build
Instalar o pacote
Ainda no diretório do aplicativo, instale o pacote da biblioteca de clientes de Números de Telefone da Comunicação do Azure para .NET usando o comando dotnet add package.
dotnet add package Azure.Communication.PhoneNumbers --version 1.0.0
Adicione uma diretiva using à parte superior de Program.cs para incluir os namespaces.
using System;
using System.Linq;
using System.Threading.Tasks;
using Azure.Communication.PhoneNumbers;
Atualize a assinatura de função Main para ser assíncrona.
static async Task Main(string[] args)
{
...
}
Autenticar o cliente
Os clientes de Número de Telefone podem ser autenticados usando a cadeia de conexão adquirida de um recurso dos Serviços de Comunicação do Azure no portal do Azure.
// Get a connection string to our Azure Communication Services resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);
Os clientes de Número de Telefone também têm a opção de autenticar com a autenticação do Microsoft Entra. Com essa opção, as variáveis de ambiente AZURE_CLIENT_SECRET, AZURE_CLIENT_ID e AZURE_TENANT_ID precisam ser configuradas para autenticação.
// Get an endpoint to our Azure Communication Services resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);
Gerenciar números de telefone
Pesquisar números de telefone disponíveis
Para comprar números de telefone, primeiro você precisa procurar números de telefone disponíveis. Para procurar números de telefone, forneça o código de área, o tipo de atribuição, as funcionalidades do número de telefone, o tipo de número de telefone e a quantidade. Observe que para números de telefone do tipo chamada gratuita, fornecer o código de área é opcional.
var capabilities = new PhoneNumberCapabilities(calling:PhoneNumberCapabilityType.None, sms:PhoneNumberCapabilityType.Outbound);
var searchOptions = new PhoneNumberSearchOptions { AreaCode = "833", Quantity = 1 };
var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync("US", PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities, searchOptions);
await searchOperation.WaitForCompletionAsync();
Comprar números de telefone
O resultado da pesquisa por números de telefone é um PhoneNumberSearchResult. Ela contém um SearchId que pode ser passado para a API de comprar números para adquirir os números na pesquisa. Observe que chamar a API de comprar números de telefone resultará em um encargo para sua conta do Azure.
var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();
Obter números de telefone
Depois de comprar um número, você poderá recuperá-lo do cliente.
var getPhoneNumberResponse = await client.GetPurchasedPhoneNumberAsync("+14255550123");
Console.WriteLine($"Phone number: {getPhoneNumberResponse.Value.PhoneNumber}, country code: {getPhoneNumberResponse.Value.CountryCode}");
Você também pode recuperar todos os números de telefone comprados.
var purchasedPhoneNumbers = client.GetPurchasedPhoneNumbersAsync();
await foreach (var purchasedPhoneNumber in purchasedPhoneNumbers)
{
Console.WriteLine($"Phone number: {purchasedPhoneNumber.PhoneNumber}, country code: {purchasedPhoneNumber.CountryCode}");
}
Atualizar as funcionalidades do número de telefone
Com um número comprado, você pode atualizar as funcionalidades.
var updateCapabilitiesOperation = await client.StartUpdateCapabilitiesAsync("+14255550123", calling: PhoneNumberCapabilityType.Outbound, sms: PhoneNumberCapabilityType.InboundOutbound);
await updateCapabilitiesOperation.WaitForCompletionAsync();
Liberar número de telefone
Você pode liberar um número de telefone comprado.
var releaseOperation = await client.StartReleasePhoneNumberAsync("+14255550123");
await releaseOperation.WaitForCompletionResponseAsync();
Executar o código
Execute o aplicativo do seu diretório de aplicativo com o comando dotnet run.
dotnet run
Exemplo de código
É possível baixar o aplicativo de exemplo do GitHub
Observação
Encontre o código finalizado para este guia de início rápido no GitHub
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 e uma cadeia de conexão dos Serviços de Comunicação implantados. Crie um recurso dos Serviços de Comunicação.
Ao configurar o
Criar um aplicativo Java
Abra o terminal ou a janela Comando. Navegue até o diretório em que você deseja criar o aplicativo Java. Execute o comando abaixo para gerar o projeto Java no modelo maven-archetype-quickstart.
mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
Você observará que a tarefa 'gerar' criou um diretório com o mesmo nome que o artifactId. Nesse diretório, o diretório src/main/java contém o código-fonte do projeto, o src/test/java directory contém a fonte de teste e o arquivo pom.xml é o Modelo de Objeto do Projeto, ou POM.
Instalar o pacote
Abra o arquivo pom.xml no seu editor de texto. Adicione os seguintes elementos de dependência ao grupo de dependências.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-common</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-phonenumbers</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.2.3</version>
</dependency>
Configurar o framework de aplicativos
No diretório do projeto:
- Navegue até o diretório /src/main/java/com/communication/quickstart
- Abra o arquivo App.java em seu editor
- Substitua a instrução
System.out.println("Hello world!"); - Adicione diretivas
import
Use o seguinte código para começar:
import com.azure.communication.phonenumbers.*;
import com.azure.communication.phonenumbers.models.*;
import com.azure.core.http.rest.*;
import com.azure.core.util.Context;
import com.azure.core.util.polling.LongRunningOperationStatus;
import com.azure.core.util.polling.PollResponse;
import com.azure.core.util.polling.SyncPoller;
import com.azure.identity.*;
import java.io.*;
public class App
{
public static void main( String[] args ) throws IOException
{
System.out.println("Azure Communication Services - Phone Numbers Quickstart");
// Quickstart code goes here
}
}
Autenticar o Cliente de Números de Telefone
O PhoneNumberClientBuilder está habilitado para usar a autenticação do Microsoft Entra
// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
.endpoint(endpoint)
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
Como alternativa, o uso do ponto de extremidade e da chave de acesso do recurso de comunicação para autenticar também é possível.
// You can find your connection string from your resource in the Azure portal
String connectionString = "endpoint=https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<ACCESS_KEY>";
PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
.connectionString(connectionString)
.buildClient();
Gerenciar números de telefone
Pesquisar números de telefone disponíveis
Para comprar números de telefone, primeiro você precisa procurar números de telefone disponíveis. Para procurar números de telefone, forneça o código de área, o tipo de atribuição, as funcionalidades do número de telefone, o tipo de número de telefone e a quantidade. Observe que para números de telefone do tipo chamada gratuita, fornecer o código de área é opcional.
PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities()
.setCalling(PhoneNumberCapabilityType.INBOUND)
.setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);
PhoneNumberSearchOptions searchOptions = new PhoneNumberSearchOptions().setAreaCode("833").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. Ela contém um searchId que pode ser passado para a API de comprar números para adquirir os números na pesquisa. Observe que chamar a API de comprar números de telefone resultará em um encargo para sua conta do Azure.
PollResponse<PhoneNumberOperation> purchaseResponse = phoneNumberClient.beginPurchasePhoneNumbers(searchId, Context.NONE).waitForCompletion();
System.out.println("Purchase phone numbers operation is: " + purchaseResponse.getStatus());
Obter números de telefone
Depois de comprar um número, você poderá recuperá-lo do cliente.
PurchasedPhoneNumber phoneNumber = phoneNumberClient.getPurchasedPhoneNumber("+14255550123");
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());
Você também pode recuperar todos os números de telefone comprados.
PagedIterable<PurchasedPhoneNumber> phoneNumbers = phoneNumberClient.listPurchasedPhoneNumbers(Context.NONE);
PurchasedPhoneNumber phoneNumber = phoneNumbers.iterator().next();
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());
Atualizar as funcionalidades do número de telefone
Com um número comprado, você pode atualizar as funcionalidades.
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
}
Liberar número de telefone
Você pode liberar um número de telefone comprado.
PollResponse<PhoneNumberOperation> releaseResponse =
phoneNumberClient.beginReleasePhoneNumber("+14255550123", Context.NONE).waitForCompletion();
System.out.println("Release phone number operation is: " + releaseResponse.getStatus());
Executar o código
Navegue até o diretório que contém o arquivo pom.xml e compile o projeto usando o comando mvn a seguir.
mvn compile
Em seguida, compile o pacote.
mvn package
Execute o comando mvn a seguir para executar o aplicativo.
mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false
A saída do aplicativo descreve cada ação concluída:
Azure Communication Services - Phone Numbers Quickstart
Searched phone numbers: [+18001234567]
Purchase phone numbers operation is: SUCCESSFULLY_COMPLETED
Phone Number Country Code: US
Phone Number Calling capabilities: inbound
Phone Number SMS capabilities: inbound
Release phone number operation is: SUCCESSFULLY_COMPLETED
Observação
Encontre o código finalizado para este guia de início rápido no GitHub
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Python 3.7+.
- Um recurso e uma cadeia de conexão dos Serviços de Comunicação implantados. Crie um recurso dos Serviços de Comunicação.
Configurando
Criar um novo aplicativo Python
Abra a janela de comando ou do terminal a fim de criar um diretório para o aplicativo e navegue até ele.
mkdir phone-numbers-quickstart && cd phone-numbers-quickstart
Use um editor de texto para criar um arquivo chamado phone_numbers_sample.py no diretório raiz do projeto e adicione o código a seguir. Vamos adicionar o código de início rápido restante nas seções a seguir.
import os
from azure.communication.phonenumbers import PhoneNumbersClient
try:
print('Azure Communication Services - Phone Numbers Quickstart')
# Quickstart code goes here
except Exception as ex:
print('Exception:')
print(ex)
Instalar o pacote
Ainda no diretório do aplicativo, instale o pacote da biblioteca de clientes da Administração dos Serviços de Comunicação do Azure para Python usando o comando pip install.
pip install azure-communication-phonenumbers
Autenticar o cliente de números de telefone
O aplicativo PhoneNumbersClient está habilitado para usar a autenticação do Microsoft Entra. Usar o objeto DefaultAzureCredential é a maneira mais fácil de começar a usar o Microsoft Entra ID e você pode instalá-lo usando o comando pip install.
pip install azure-identity
A criação de um objeto DefaultAzureCredential requer que você já tenha AZURE_CLIENT_ID, AZURE_CLIENT_SECRET e AZURE_TENANT_ID definidos como variáveis de ambiente com seus valores correspondentes do aplicativo Microsoft Entra registrado.
Para obter uma rápida explicação sobre como obter essas variáveis de ambiente, siga o Início rápido para configurar entidades de serviço na CLI.
Depois de instalar a biblioteca azure-identity, podemos continuar autenticando o cliente.
import os
from azure.communication.phonenumbers import PhoneNumbersClient
from azure.identity import DefaultAzureCredential
# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
credential = DefaultAzureCredential()
phone_numbers_client = PhoneNumbersClient(endpoint, credential)
except Exception as ex:
print('Exception:')
print(ex)
Como alternativa, o uso do ponto de extremidade e da chave de acesso do recurso de comunicação para autenticar também é possível.
import os
from azure.communication.phonenumbers import PhoneNumbersClient
# You can find your connection string from your resource in the Azure portal
connection_string = 'https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
phone_numbers_client = PhoneNumbersClient.from_connection_string(connection_string)
except Exception as ex:
print('Exception:')
print(ex)
Funções
Depois que PhoneNumbersClient tiver sido autenticado, podemos começar a trabalhar nas diferentes funções que ele pode fazer.
Pesquisar números de telefone disponíveis
Para comprar números de telefone, você deve primeiro procurar por números de telefone disponíveis. Para procurar por números de telefone, forneça o código de área, o tipo de atribuição, as funcionalidades do número de telefone, o tipo do número de telefone e a quantidade (a quantidade padrão é definida como 1). Observe que para números de telefone do tipo chamada gratuita, fornecer o código de área é opcional.
import os
from azure.communication.phonenumbers import PhoneNumbersClient, PhoneNumberCapabilityType, PhoneNumberAssignmentType, PhoneNumberType, PhoneNumberCapabilities
from azure.identity import DefaultAzureCredential
# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
credential = DefaultAzureCredential()
phone_numbers_client = PhoneNumbersClient(endpoint, credential)
capabilities = PhoneNumberCapabilities(
calling = PhoneNumberCapabilityType.INBOUND,
sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
)
search_poller = phone_numbers_client.begin_search_available_phone_numbers(
"US",
PhoneNumberType.TOLL_FREE,
PhoneNumberAssignmentType.APPLICATION,
capabilities,
polling = True
)
search_result = search_poller.result()
print ('Search id: ' + search_result.search_id)
phone_number_list = search_result.phone_numbers
print('Reserved phone numbers:')
for phone_number in phone_number_list:
print(phone_number)
except Exception as ex:
print('Exception:')
print(ex)
Comprar números de telefone
O resultado da pesquisa por números de telefone é um PhoneNumberSearchResult. Ela contém um searchId que pode ser passado para a API de comprar números para adquirir os números na pesquisa. Observe que chamar a API de comprar números de telefone resultará em um encargo para sua conta do Azure.
import os
from azure.communication.phonenumbers import (
PhoneNumbersClient,
PhoneNumberCapabilityType,
PhoneNumberAssignmentType,
PhoneNumberType,
PhoneNumberCapabilities
)
from azure.identity import DefaultAzureCredential
# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
credential = DefaultAzureCredential()
phone_numbers_client = PhoneNumbersClient(endpoint, credential)
capabilities = PhoneNumberCapabilities(
calling = PhoneNumberCapabilityType.INBOUND,
sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
)
search_poller = phone_numbers_client.begin_search_available_phone_numbers(
"US",
PhoneNumberType.TOLL_FREE,
PhoneNumberAssignmentType.APPLICATION,
capabilities,
area_code="833",
polling = True
)
search_result = poller.result()
print ('Search id: ' + search_result.search_id)
phone_number_list = search_result.phone_numbers
print('Reserved phone numbers:')
for phone_number in phone_number_list:
print(phone_number)
purchase_poller = phone_numbers_client.begin_purchase_phone_numbers(search_result.search_id, polling = True)
purchase_poller.result()
print("The status of the purchase operation was: " + purchase_poller.status())
except Exception as ex:
print('Exception:')
print(ex)
Obter números de telefone comprados
Depois de comprar um número, você poderá recuperá-lo do cliente.
purchased_phone_number_information = phone_numbers_client.get_purchased_phone_number("+18001234567")
print('Phone number: ' + purchased_phone_number_information.phone_number)
print('Country code: ' + purchased_phone_number_information.country_code)
Você também pode recuperar todos os números de telefone comprados.
purchased_phone_numbers = phone_numbers_client.list_purchased_phone_numbers()
print('Purchased phone numbers:')
for purchased_phone_number in purchased_phone_numbers:
print(purchased_phone_number.phone_number)
Atualizar as funcionalidades do número de telefone
Você pode atualizar as funcionalidades de um número de telefone adquirido anteriormente.
update_poller = phone_numbers_client.begin_update_phone_number_capabilities(
"+18001234567",
PhoneNumberCapabilityType.OUTBOUND,
PhoneNumberCapabilityType.OUTBOUND,
polling = True
)
update_poller.result()
print('Status of the operation: ' + update_poller.status())
Liberar número de telefone
Você pode liberar um número de telefone comprado.
release_poller = phone_numbers_client.begin_release_phone_number("+18001234567")
release_poller.result()
print('Status of the operation: ' + release_poller.status())
Executar o código
No prompt do console, navegue até o diretório que contém o arquivo phone_numbers_sample.py e execute o comando Python a seguir para executar o aplicativo.
python phone_numbers_sample.py
Observação
Encontre o código finalizado para este guia de início rápido no GitHub
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Node.js, versões Active LTS e Maintenance LTS (8.11.1 e 10.14.1 recomendadas).
- Um recurso e uma cadeia de conexão ativos dos Serviços de Comunicação. Crie um recurso dos Serviços de Comunicação.
Verificação de pré-requisitos
- Em uma janela de terminal ou de comando, execute
node --versionpara verificar se o Node.js está instalado.
Configurando
Criar um aplicativo Node.js
Primeiro, abra a janela de comando ou do terminal para criar um diretório para seu aplicativo e navegue até ele.
mkdir phone-numbers-quickstart && cd phone-numbers-quickstart
Execute npm init -y para criar um arquivo package.json com as configurações padrão.
npm init -y
Crie um arquivo chamado phone-numbers-quickstart.js na raiz do diretório que você acabou de criar. Adicione o seguinte snippet a ele:
async function main() {
// quickstart code will here
}
main();
Instalar o pacote
Use o comando npm install para instalar a biblioteca de clientes de Números de Telefone dos Serviços de Comunicação do Azure para JavaScript.
npm install @azure/communication-phone-numbers --save
A opção --save adiciona a biblioteca como uma dependência no arquivo package.json.
Autenticar o cliente
Importe o PhoneNumbersClient da biblioteca de clientes e crie uma instância dele com sua cadeia de conexão. O código abaixo recupera a cadeia de conexão do recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerenciar a cadeia de conexão do seu recurso.
Adicione o seguinte código à parte superior de phone-numbers-quickstart.js:
const { PhoneNumbersClient } = require('@azure/communication-phone-numbers');
// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
// Instantiate the phone numbers client
const phoneNumbersClient = new PhoneNumbersClient(connectionString);
Gerenciar números de telefone
Pesquisar números de telefone disponíveis
Para comprar números de telefone, primeiro você precisa procurar números de telefone disponíveis. Para procurar números de telefone, forneça o código de área, o tipo de atribuição, as funcionalidades do número de telefone, o tipo de número de telefone e a quantidade. Observe que para números de telefone do tipo chamada gratuita, fornecer o código de área é opcional.
Adicione o snippet a seguir à sua função main:
/**
* Search for Available Phone Number
*/
// Create search request
const searchRequest = {
countryCode: "US",
phoneNumberType: "tollFree",
assignmentType: "application",
capabilities: {
sms: "outbound",
calling: "none"
},
areaCode: "833",
quantity: 1
};
const searchPoller = await phoneNumbersClient.beginSearchAvailablePhoneNumbers(searchRequest);
// The search is underway. Wait to receive searchId.
const { searchId, phoneNumbers } = await searchPoller.pollUntilDone();
const phoneNumber = phoneNumbers[0];
console.log(`Found phone number: ${phoneNumber}`);
console.log(`searchId: ${searchId}`);
Comprar número de telefone
O resultado da pesquisa por números de telefone é um PhoneNumberSearchResult. Ela contém um searchId que pode ser passado para a API de comprar números para adquirir os números na pesquisa. Observe que chamar a API de comprar números de telefone resultará em um encargo para sua conta do Azure.
Adicione o snippet a seguir à sua função main:
/**
* Purchase Phone Number
*/
const purchasePoller = await phoneNumbersClient.beginPurchasePhoneNumbers(searchId);
// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumber}`);
Atualizar as funcionalidades do número de telefone
Com o número de telefone comprado, adicione o seguinte código para atualizar as funcionalidades dele:
/**
* Update Phone Number Capabilities
*/
// Create update request.
// This will update phone number to send and receive sms, but only send calls.
const updateRequest = {
sms: "inbound+outbound",
calling: "outbound"
};
const updatePoller = await phoneNumbersClient.beginUpdatePhoneNumberCapabilities(
phoneNumber,
updateRequest
);
// Update is underway.
await updatePoller.pollUntilDone();
console.log("Phone number updated successfully.");
Obter números de telefone comprados
Depois de comprar um número, você poderá recuperá-lo do cliente. Adicione o seguinte código à sua função main para obter o número de telefone que você acabou de comprar:
/**
* Get Purchased Phone Number
*/
const { capabilities } = await phoneNumbersClient.getPurchasedPhoneNumber(phoneNumber);
console.log("These capabilities:", capabilities, "should be the same as these:", updateRequest, ".");
Você também pode recuperar todos os números de telefone comprados.
const purchasedPhoneNumbers = await phoneNumbersClient.listPurchasedPhoneNumbers();
for await (const purchasedPhoneNumber of purchasedPhoneNumbers) {
console.log(`Phone number: ${purchasedPhoneNumber.phoneNumber}, country code: ${purchasedPhoneNumber.countryCode}.`);
}
Liberar número de telefone
Você também pode liberar todos os números de telefone comprados. Adicione o snippet de código abaixo à sua função main:
/**
* Release Purchased Phone Number
*/
const releasePoller = await phoneNumbersClient.beginReleasePhoneNumber(phoneNumber);
// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");
Executar o código
Use o comando node para executar o código adicionado ao arquivo phone-numbers-quickstart.js.
node phone-numbers-quickstart.js
Solução de problemas
Perguntas e problemas comuns:
Quando um número de telefone é liberado, ele aparece no seu recurso de ACS no portal do Azure até o final do período de cobrança. Ele não pode ser readquirido até o final do ciclo de cobrança.
Quando um recurso dos Serviços de Comunicação é excluído, os números de telefone associados a ele são liberados automaticamente ao mesmo tempo.
Próximas etapas
Neste guia de início rápido, você aprendeu a:
- Comprar um número de telefone
- Gerenciar seu número de telefone
- Liberar um número de telefone
- Enviar aplicativo de verificação gratuita (veja se necessário)