Guia de 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 em que você está operando, conforme determinado pelo seu endereço de cobrança do Azure. Para obter mais informações, visite a documentação de elegibilidade da assinatura.

Importante

Para encomendas de grande volume ou no caso de o seu número de telefone desejado não estar 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á para o recurso Serviços de Comunicação no portal do Azure.

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

Pesquisar números de telefone disponíveis

Navegue até a folha Números de Telefone no menu de recursos.

Captura de ecrã a mostrar a página telefónica de um recurso dos Serviços de Comunicação.

Pressione o botão Obter para iniciar o assistente. O assistente na folha Números de telefone irá guiá-lo através de uma série de perguntas que o ajudam a escolher o número de telefone que melhor se adapta ao seu cenário.

Primeiro, terá de escolher o País/região onde pretende fornecer o número de telefone. Depois de selecionar o País/região, você precisará selecionar o Caso de uso que melhor atende às suas necessidades.

Captura de ecrã a mostrar a vista Obter números de telefone.

Selecione as funcionalidades do seu número de telefone

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

  1. A seleção do tipo de número
  2. A seleção das capacidades numéricas

Você pode selecionar entre dois tipos de número de telefone: Local e Gratuito. Depois de selecionar um tipo de número, você pode escolher o recurso.

No nosso exemplo, selecionámos um tipo de número gratuito com as funcionalidades Efetuar chamadas e Enviar e receber SMS .

Captura de ecrã a mostrar a vista Selecionar funcionalidades.

A partir daqui, clique no botão Avançar: Números na parte inferior da página para personalizar o(s) número(s) de telefone que você gostaria de provisionar.

Personalização de números de telefone

Na página Números, você personalizará o(s) número(s) de telefone que deseja provisionar.

Captura de ecrã a mostrar a página de seleção Números.

Nota

Este guia de início rápido está mostrando o fluxo de personalização do tipo Número gratuito . A experiência pode 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 e insira a quantidade que você deseja provisionar e, em seguida, clique em Pesquisar para encontrar números que atendam aos requisitos selecionados. Os números de telefone que atendem às suas necessidades serão mostrados juntamente com seu custo mensal.

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

Nota

A disponibilidade depende do tipo de número, da localização e das funcionalidades que selecionou. Os números são reservados por um curto período de tempo antes que a transação expire. Se a transação expirar, você precisará selecionar novamente os números.

Para ver o resumo da compra e fazer a sua encomenda, clique no botão Seguinte: Resumo na parte inferior da página.

Comprar números de telefone

A página de resumo analisará o tipo de número, recursos, números de telefone e custo mensal total para provisionar os números de telefone.

Nota

Os preços apresentados são os encargos mensais recorrentes que cobrem o custo de alugar o número de telefone selecionado para você. Não estão incluídos nesta vista os custos pré-pagos que são incorridos quando faz ou recebe chamadas. As tabelas de preços estão disponíveis aqui. Estes custos dependem do tipo de número e dos destinos chamados. Por exemplo, o preço por minuto de uma chamada de um número regional de Seattle para um número regional em Nova Iorque e de uma chamada do mesmo número para um número de telemóvel do Reino Unido pode ser diferente.

Por fim, clique em Fazer pedido na parte inferior da página para confirmar.

Captura de ecrã a mostrar a página Resumo com o tipo de número, Funcionalidades, Números de telefone e Custo mensal total apresentados.

Encontre seus números de telefone no portal do Azure

Navegue até o recurso dos Serviços de Comunicação do Azure no portal do Azure:

Captura de ecrã a mostrar a página principal de um Recurso de Serviços de Comunicação.

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

Captura de ecrã a mostrar a página do número de telefone de um Recurso de Serviços de Comunicação.

Nota

Pode levar alguns minutos para que os números provisionados sejam mostrados nesta página.

Atualizar recursos de número de telefone

Na página Números de telefone , você pode selecionar um número de telefone para configurá-lo.

Captura de tela mostrando a página de recursos de atualização.

Selecione os recursos nas opções disponíveis e clique em Salvar para aplicar sua seleção.

Número de telefone de lançamento

Na página Números, você pode liberar números de telefone.

Captura de tela mostrando a página de números de telefone de lançamento.

Selecione o número de telefone que você deseja liberar e, em seguida, clique no botão Liberar .

Importante

Esta funcionalidade dos Serviços de Comunicação do Azure está atualmente em pré-visualização.

As APIs e SDKs de visualização são fornecidos sem um contrato de nível de serviço. Recomendamos que você não os use para cargas de trabalho de produção. Alguns recursos podem não ser suportados ou podem ter recursos restritos.

Para obter mais informações, consulte Termos de Utilização Suplementares para Pré-visualizações do Microsoft Azure.

Os Serviços de Comunicação do Azure estão a introduzir uma nova experiência de utilizador para a compra de números de telefone. Essa experiência está sendo veiculada no momento, e você pode ser apresentado a essa experiência ao comprar um número de telefone no portal do Azure. Se você tiver comentários sobre essa experiência, não hesite em fornecê-los por meio do botão Dar 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 ecrã a mostrar a página principal de um recurso dos Serviços de Comunicação.

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

    Captura de ecrã a mostrar a página de números de telefone de um recurso dos Serviços de Comunicação.

  3. Selecione Obter no canto superior esquerdo da página para comprar seu número de telefone. Selecionar esta opção inicia o nosso assistente de compras:

    Captura de ecrã a mostrar o assistente de pesquisa do carrinho de compras do número de telefone.

  4. Escolha o País/região onde pretende fornecer o número de telefone. A disponibilidade do país baseia-se na localização de faturação da sua subscrição do Azure. Mais informações sobre os números disponíveis para cada país podem ser encontradas aqui. Em seguida, você escolherá o tipo de número. Você pode selecionar entre dois tipos de número de telefone: Local e Gratuito.

  5. Selecione Pesquisar para obter números que atendam aos critérios selecionados. Tem vários filtros para procurar o número que se adequa às suas necessidades, incluindo:

    • Caso de uso: é para saber se você está usando esse número para ligar de um aplicativo (A2P) ou de um agente humano (P2P).
    • Chamada: destina-se a determinar as capacidades de Chamada que pretende para o seu número de telefone: Fazer chamadas e/ou receber chamadas.
    • SMS: Isto é para determinar os recursos de SMS que você gostaria 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 conjunto de dígitos em seu número de telefone.

    Captura de ecrã a mostrar 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 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 seu carrinho seja automaticamente liberado.

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

    Nota

    Os preços apresentados são os encargos mensais recorrentes que cobrem o custo de alugar o número de telefone selecionado para você. Não estão incluídos nesta vista os custos pré-pagos que são incorridos quando faz ou recebe chamadas. As tabelas de preços estão disponíveis aqui. Estes custos dependem do tipo de número e dos destinos chamados. Por exemplo, o preço por minuto de uma chamada de um número regional de Seattle para um número regional em Nova Iorque e de uma chamada do mesmo número para um número de telemóvel do Reino Unido pode ser diferente.

  7. Selecione Avançar para rever sua compra. Para concluir a compra, selecione Comprar agora.

    Captura de ecrã a mostrar 2 números de telefone para rever e comprar.

  8. Você pode encontrar seus números comprados novamente na página Números de telefone. Pode levar alguns minutos para que os números sejam provisionados.

    Captura de ecrã da página de números de telefone com os números de telefone recém-comprados encaixotados com um limite vermelho.

Atualizar recursos de número de telefone

Na página Números de telefone , você pode selecionar um número de telefone para configurá-lo.

Captura de tela mostrando a página de recursos de atualização.

Selecione os recursos nas opções disponíveis e, em seguida, selecione Salvar para aplicar sua seleção.

Número de telefone de lançamento

Na página Números, você pode liberar números de telefone.

Captura de tela mostrando a página de números de telefone de lançamento.

Selecione o número de telefone que você deseja liberar e, em seguida, selecione no botão Liberar .

Pré-requisitos

Configuração

Adicionar a extensão

Adicione a extensão dos Serviços de Comunicação do Azure para a CLI do Azure usando o az extension comando.

az extension add --name communication

Iniciar sessão na CLI do Azure

Você precisará entrar na CLI do Azure. Você pode entrar executando o az login comando do terminal e fornecendo suas credenciais.

Operações

Listar número(s) de telefone comprado(s)

Execute o seguinte comando para recuperar todos os números de telefone comprados.

az communication phonenumber list --connection-string "<yourConnectionString>"

Faça esta substituição no código:

  • Substitua <yourConnectionString> pela cadeia de conexão.

Obter detalhes do número de telefone comprado

Execute o seguinte comando 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 Serviços de Comunicação.
  • Substitua <yourConnectionString> pela cadeia de conexão.

Nota

A opção CLI do Azure fornece funcionalidade apenas para listar e mostrar números de telefone. Ele não suporta outras operações, como pesquisar, comprar, editar ou liberar números de telefone.

(Opcional) Usar operações de números de telefone da CLI do Azure sem passar em uma cadeia de conexão

Você pode configurar a variável de ambiente para usar operações AZURE_COMMUNICATION_CONNECTION_STRING de números de telefone da CLI do Azure sem precisar usar --connection_string para passar na cadeia de conexão. Para configurar uma variável de ambiente, abra uma janela do console e selecione seu sistema operacional nas guias abaixo. Substitua <yourConnectionString> pela cadeia de conexão real.

Abra uma janela do console e digite o seguinte comando:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Depois de adicionar a variável de ambiente, poderá ter de reiniciar todos os programas em execução que irão precisar de ler a variável de ambiente, incluindo a janela da consola. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Nota

Encontre o código finalizado para este início rápido no GitHub

Pré-requisitos

Verificação de pré-requisitos

  • Em um terminal ou janela de comando, execute o dotnet comando para verificar se a biblioteca de cliente .NET está instalada.

Configuração

Criar um novo aplicativo C#

Em uma janela de console (como cmd, PowerShell ou Bash), use o dotnet new comando para criar um novo aplicativo de console com o nome PhoneNumbersQuickstart. Este comando cria um projeto C# "Hello World" simples com um único arquivo de origem: Program.cs.

dotnet new console -o PhoneNumbersQuickstart

Altere seu diretório para a pasta do aplicativo recém-criada e use o dotnet build comando para compilar seu aplicativo.

cd PhoneNumbersQuickstart
dotnet build

Instalar o pacote

Enquanto ainda estiver no diretório do aplicativo, instale a biblioteca de cliente do Azure Communication PhoneNumbers para o pacote .NET usando o dotnet add package comando.

dotnet add package Azure.Communication.PhoneNumbers --version 1.0.0

Adicione uma using diretiva à parte superior do Program.cs para incluir os namespaces.

using System;
using System.Linq;
using System.Threading.Tasks;
using Azure.Communication.PhoneNumbers;

Atualize Main a assinatura da função 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, AZURE_CLIENT_SECRETas variáveis , AZURE_CLIENT_ID e AZURE_TENANT_ID de ambiente 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);

Gerir números de telefone

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 pesquisar números de telefone, forneça o código de área, o tipo de atribuição, os recursos do número de telefone, o tipo de número de telefone e a quantidade. Note que para o tipo de número de telefone gratuito, 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 de números de telefone é um PhoneNumberSearchResultarquivo . Isso contém um SearchId que pode ser passado para a API de números de compra para adquirir os números na pesquisa. Observe que chamar a API de números de telefone de compra resultará em uma cobrança para sua Conta do Azure.

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

Obter número(s) de telefone

Após um número de compra, você pode 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 recursos de número de telefone

Com um número comprado, você pode atualizar os recursos.

var updateCapabilitiesOperation = await client.StartUpdateCapabilitiesAsync("+14255550123", calling: PhoneNumberCapabilityType.Outbound, sms: PhoneNumberCapabilityType.InboundOutbound);
await updateCapabilitiesOperation.WaitForCompletionAsync();

Número de telefone de lançamento

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 a partir do diretório do aplicativo com o dotnet run comando.

dotnet run

Código de Exemplo

Você pode baixar o aplicativo de exemplo do GitHub

Nota

Encontre o código finalizado para este início rápido no GitHub

Pré-requisitos

Configuração

Criar uma nova aplicação Java

Abra o terminal ou a janela de comando. Navegue até o diretório onde você gostaria de criar seu aplicativo Java. Execute o comando abaixo para gerar o projeto Java a partir do modelo maven-archetype-quickstart.

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Você notará que a tarefa 'gerar' criou um diretório com o mesmo nome do artifactId. Neste 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 pom.xml arquivo é o Project Object Model ou POM do projeto.

Instalar o pacote

Abra o arquivo pom.xml no 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 a estrutura do aplicativo

No diretório do projeto:

  1. Navegue até o diretório /src/main/java/com/communication/quickstart
  2. Abra o arquivo App.java no editor
  3. Substitua a System.out.println("Hello world!"); instrução
  4. Adicionar import diretivas

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, usar o ponto de extremidade e a 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, você deve primeiro procurar por números de telefone disponíveis. Para pesquisar números de telefone, forneça o código de área, o tipo de atribuição, os recursos do número de telefone, o tipo de número de telefone e a quantidade. Note que para o tipo de número de telefone gratuito, 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 de números de telefone é um PhoneNumberSearchResult. Isso contém um searchId que pode ser passado para a API de números de compra para adquirir os números na pesquisa. Observe que chamar a API de números de telefone de compra resultará em uma cobrança 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úmero(s) de telefone

Após um número de compra, você pode 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 recursos de número de telefone

Com um número comprado, você pode atualizar os recursos.

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
}

Número de telefone de lançamento

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 seguinte mvn comando.

mvn compile

Em seguida, compile o pacote.

mvn package

Execute o seguinte mvn comando 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

Nota

Encontre o código finalizado para este início rápido no GitHub

Pré-requisitos

Configuração

Criar uma aplicação Python nova

Abra o terminal ou a janela de comando e crie um novo diretório para seu 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. Adicionaremos 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

Enquanto ainda estiver no diretório do aplicativo, instale a biblioteca de cliente da Administração dos Serviços de Comunicação do Azure para o pacote Python usando o pip install comando.

pip install azure-communication-phonenumbers

Autenticar o cliente de números de telefone

O PhoneNumbersClient está habilitado para usar a autenticação do Microsoft Entra. Usar o objeto é a maneira mais fácil de começar a usar o DefaultAzureCredential Microsoft Entra ID e você pode instalá-lo usando o pip install comando.

pip install azure-identity

Criar um DefaultAzureCredential objeto requer que você tenha AZURE_CLIENT_ID, AZURE_CLIENT_SECRETe AZURE_TENANT_ID já definido como variáveis de ambiente com seus valores correspondentes do seu aplicativo Microsoft Entra registrado.

Para obter um rápido aumento sobre como obter essas variáveis de ambiente, você pode seguir o Guia de início rápido Configurar entidades de serviço da CLI.

Depois de instalar a azure-identity biblioteca, 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, usar o ponto de extremidade e a 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

PhoneNumbersClient Uma vez 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 quaisquer números de telefone disponíveis. Para pesquisar números de telefone, forneça o código de área, o tipo de atribuição, os recursos do número de telefone, o tipo de número de telefone e a quantidade (a quantidade padrão é definida como 1). Note que para o tipo de número de telefone gratuito, 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 de números de telefone é um PhoneNumberSearchResultarquivo . Isso contém um searchId que pode ser passado para a API de números de compra para adquirir os números na pesquisa. Observe que chamar a API de números de telefone de compra resultará em uma cobrança 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úmero(s) de telefone comprado(s)

Após um número de compra, você pode 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 recursos de número de telefone

Você pode atualizar os recursos de um número de telefone comprado 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())

Número de telefone de lançamento

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

Em um prompt do console, navegue até o diretório que contém o arquivo phone_numbers_sample.py e, em seguida, execute o seguinte comando Python para executar o aplicativo.

python phone_numbers_sample.py

Nota

Encontre o código finalizado para este início rápido no GitHub

Pré-requisitos

  • Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
  • Node.js versões Ative LTS e Maintenance LTS (8.11.1 e 10.14.1 recomendadas).
  • Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Crie um recurso de Serviços de Comunicação.

Verificação de pré-requisitos

  • Em um terminal ou janela de comando, execute node --version para verificar se Node.js está instalado.

Configuração

Criar um novo aplicativo Node.js

Primeiro, abra o terminal ou a janela de comando, crie um novo 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 trecho a ele:

async function main() {
    // quickstart code will here
}

main();

Instalar o pacote

Use o npm install comando para instalar a biblioteca de cliente Números de Telefone dos Serviços de Comunicação do Azure para JavaScript.

npm install @azure/communication-phone-numbers --save

A --save opção adiciona a biblioteca como uma dependência em seu arquivo package.json .

Autenticar o cliente

Importe o PhoneNumbersClient da biblioteca do cliente e instancie-o com sua cadeia de conexão. O código abaixo recupera a cadeia de conexão para o recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerir a cadeia de ligação do seu recurso.

Adicione o seguinte código à parte superior do 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);

Gerir números de telefone

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 pesquisar números de telefone, forneça o código de área, o tipo de atribuição, os recursos do número de telefone, o tipo de número de telefone e a quantidade. Note que para o tipo de número de telefone gratuito, fornecer o código de área é opcional.

Adicione o seguinte trecho à sua main função:

/**
 * 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}`);

Número de telefone da compra

O resultado da pesquisa de números de telefone é um PhoneNumberSearchResultarquivo . Isso contém um searchId que pode ser passado para a API de números de compra para adquirir os números na pesquisa. Observe que chamar a API de números de telefone de compra resultará em uma cobrança para sua Conta do Azure.

Adicione o seguinte trecho à sua main função:

/**
 * Purchase Phone Number
 */

const purchasePoller = await phoneNumbersClient.beginPurchasePhoneNumbers(searchId);

// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumber}`);

Atualizar recursos de número de telefone

Com um número de telefone agora comprado, adicione o seguinte código para atualizar seus recursos:

/**
 * 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úmero(s) de telefone comprado(s)

Após um número de compra, você pode recuperá-lo do cliente. Adicione o seguinte código à sua main função para obter o número de telefone que 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}.`);
}

Número de telefone de lançamento

Agora você pode liberar o número de telefone comprado. Adicione o trecho de código abaixo à sua main função:

/**
 * 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 node comando para executar o código adicionado ao arquivo phone-numbers-quickstart.js .

node phone-numbers-quickstart.js

Resolução de Problemas

Perguntas e problemas comuns:

  • Quando um número de telefone é lançado, o número de telefone aparece no recurso ACS no portal do Azure até o final do ciclo de cobrança. Também não pode ser recomprado até ao final do ciclo de faturação.

  • Quando um recurso dos Serviços de Comunicação é excluído, os números de telefone associados a esse recurso são liberados automaticamente ao mesmo tempo.

Próximos passos

Neste guia de início rápido, você aprendeu como:

Enviar um SMS

Verificação gratuita

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

Introdução às chamadas em aplicações