Início Rápido: Obter e gerenciar números de telefone

  • Artigo

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

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.

Captura de tela mostrando a página principal de um recurso dos Serviços de Comunicação.

Pesquisar números de telefone disponíveis

Acesse a folha Números de Telefone no menu de recursos.

Captura de tela mostrando a página de telefone de um recurso dos Serviços de Comunicação.

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.

Captura de tela mostrando a exibição Obter números de telefone.

Selecionar os recursos de número de telefone

A configuração do número de telefone é dividida em duas etapas:

  1. A seleção do tipo de número
  2. 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.

Captura de tela que mostra a exibição Selecionar recursos.

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.

Captura de tela mostrando a página de seleção de Números.

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.

Captura de tela mostrando a página de seleção de Números com números reservados.

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.

Captura de tela mostrando a página de Resumo com o Tipo de número, os Recursos, os Números de telefone e o Custo mensal total.

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:

Captura de tela mostrando a página principal de um Recurso dos Serviços de Comunicação.

Selecione a folha Números de Telefone no menu para gerenciar seus números de telefone.

Captura de tela mostrando a página de número de telefone de um Recurso dos Serviços de Comunicação.

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.

Captura de tela que mostra a página Atualizar recursos.

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.

Captura de tela mostrando a página de liberação de 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

Comprar um número de telefone

  1. Navegue até o recurso do Serviço de Comunicação no portal do Azure.

    Captura de tela mostrando a página principal de um recurso dos Serviços de Comunicação.

  2. Na visão geral do recurso dos Serviços de Comunicação, selecione na opção "Números de telefone" no menu à esquerda.

    Captura de tela mostrando a página de números de telefone dos Serviços de Comunicação.

  3. 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:

    Captura de tela mostrando o assistente de pesquisa de carrinho de compras do número de telefone.

  4. Escolha o País/região em que deseja provisionar o número de telefone. A disponibilidade do país é 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 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.

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

    Captura de tela mostrando a página de compra do número de telefone, com os números de telefone disponíveis.

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

    Captura de tela mostrando o carrinho de compras do número de telefone, com dois números de telefone no carrinho.

    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.

  7. Selecione Avançar para revisar sua aquisição. Para concluir a aquisição, selecione Comprar agora.

    Captura de tela mostrando dois números de telefone para revisão e compra.

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

    Captura de tela da página de números de telefone com os números de telefone recém-comprados delimitados com uma borda vermelha.

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.

Captura de tela que mostra a página Atualizar recursos.

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.

Captura de tela mostrando a página de liberação de números de telefone.

Selecione o número de telefone que deseja liberar e selecione o botão Liberar.

Pré-requisitos

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

Verificação de pré-requisitos

  • Em um terminal ou janela de comando, execute o comando dotnet para 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

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:

  1. Navegue até o diretório /src/main/java/com/communication/quickstart
  2. Abra o arquivo App.java em seu editor
  3. Substitua a instrução System.out.println("Hello world!");
  4. 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

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

Verificação de pré-requisitos

  • Em uma janela de terminal ou de comando, execute node --version para 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)

Enviar um SMS

Verificação por chamada gratuita

Criar fluxo de trabalho para chamadas de saída usando os números de telefone comprados

Introdução à chamada em aplicativos