Compartilhar via

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

  • Artigo

A biblioteca de números de telefone fornece recursos para administração de números de telefone.

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

Introdução

Pré-requisitos

  • Uma assinatura do Azure.
  • Um recurso existente dos Serviços de Comunicação. Se você precisar criar o recurso, poderá usar o Portal do Azure, o do Azure PowerShell ou a CLI do Azure .

Instalar

npm install @azure/communication-phone-numbers

Suporte ao navegador

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

Principais conceitos

Esse SDK fornece funcionalidade para gerenciar facilmente direct offer e direct routing números.

Os números de direct offer vêm em dois tipos: Geográfico e Gratuito. Planos telefônicos geográficos são planos telefônicos associados a um local, cujos códigos de área de números de telefone estão associados ao código de área de uma localização geográfica. Toll-Free planos telefônicos são planos telefônicos não associados ao local. Por exemplo, nos EUA, números gratuitos podem vir com códigos de área, como 800 ou 888. Eles são gerenciados usando o PhoneNumbersClient

O recurso direct routing permite conectar sua infraestrutura de telefonia existente ao ACS. A configuração é gerenciada usando o SipRoutingClient, que fornece métodos para configurar troncos SIP e regras de roteamento de voz, a fim de lidar corretamente com chamadas para sua sub-rede de telefonia.

Cliente de números de telefone

Tipos de número de telefone

Números de telefone vêm em dois tipos; Geográfico e gratuito. Números de telefone geográficos são números de telefone associados a um local, cujos códigos de área estão associados ao código de área de uma localização geográfica. Toll-Free números de telefone não estão associados a um local. Por exemplo, nos EUA, números gratuitos podem vir com códigos de área, como 800 ou 888.

Todos os números de telefone geográficos no mesmo país são agrupados em um grupo de planos telefônicos com um tipo de número de telefone geográfico. Todos os Toll-Free números de telefone no mesmo país são agrupados em um grupo de planos telefônicos.

Pesquisando e adquirindo números

Os números de telefone podem ser pesquisados por meio da API de criação da pesquisa fornecendo um tipo de número de telefone (geográfico ou gratuito), tipo de atribuição (pessoa ou aplicativo), recursos de chamada e sms, um código de área e quantidade de números de telefone. A quantidade fornecida de números de telefone será reservada por 15 minutos. Essa pesquisa de números de telefone pode ser cancelada ou comprada. Se a pesquisa for cancelada, os números de telefone ficarão disponíveis para outras pessoas. Se a pesquisa for comprada, os números de telefone serão adquiridos para o recurso do Azure.

Configurando números de telefone

Os números de telefone podem ter uma combinação de funcionalidades. Eles podem ser configurados para dar suporte à chamada de entrada e/ou de saída ou também se você não usar o número de telefone para chamar. O mesmo se aplica aos recursos de sms.

É importante considerar o tipo de atribuição do seu número de telefone. Alguns recursos são restritos a um tipo de atribuição específico.

Cliente de roteamento SIP

O recurso de roteamento direto permite conectar a infraestrutura de telefonia fornecida pelo cliente aos Recursos de Comunicação do Azure. Para configurar a configuração de roteamento corretamente, o cliente precisa fornecer a configuração do tronco SIP e as regras de roteamento SIP para chamadas. O cliente de roteamento SIP fornece a interface necessária para definir essa configuração.

Quando uma chamada é feita, o sistema tenta corresponder o número de destino com padrões de número regex de rotas definidas. A primeira rota para corresponder ao número será selecionada. A ordem de correspondência regex é a mesma que a ordem das rotas na configuração, portanto, a ordem das rotas importa. Depois que uma rota é correspondida, a chamada é roteada para o primeiro tronco na lista de troncos da rota. Se o tronco não estiver disponível, o próximo tronco da lista será selecionado.

Exemplos

Autenticação

Para criar um objeto cliente para acessar a API dos Serviços de Comunicação, você precisará de um connection string ou o endpoint do recurso dos Serviços de Comunicação e um credential. O cliente números de telefone pode usar credenciais do Azure Active Directory ou uma credencial de chave de API para autenticar.

Você pode obter uma chave e/ou cadeia de conexão do recurso dos Serviços de Comunicação no portal do Azure. Você também pode encontrar o ponto de extremidade do recurso dos Serviços de Comunicação no portal do Azure.

Depois de ter uma chave, você pode autenticar o cliente com qualquer um dos seguintes métodos:

Usando uma cadeia de conexão

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

import { SipRoutingClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new SipRoutingClient(connectionString);

Usando uma chave de acesso com AzureKeyCredential

Se você usar uma chave para inicializar o cliente, também precisará fornecer o ponto de extremidade apropriado. Você pode obter esse ponto de extremidade do recurso dos Serviços de Comunicação no portal do Azure. Depois de ter uma chave e um ponto de extremidade, você poderá autenticar com o seguinte código:

import { AzureKeyCredential } from "@azure/core-auth";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new AzureKeyCredential("<key-from-resource>");
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

import { AzureKeyCredential } from "@azure/core-auth";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new AzureKeyCredential("<key-from-resource>");
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

Usando uma credencial do Azure Active Directory

A autenticação de cadeia de conexão é usada na maioria dos exemplos, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de identidade do Azure. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o pacote @azure/identity:

npm install @azure/identity

O pacote @azure/identity fornece uma variedade de tipos de credencial que seu aplicativo pode usar para fazer isso. O README para @azure/identity fornece mais detalhes e exemplos para você começar.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

Uso

As seções a seguir fornecem snippets de código que abrangem algumas das tarefas comuns usando o cliente de Números de Telefone dos Serviços de Comunicação do Azure. Os cenários abordados aqui consistem em:

PhoneNumbersClient

SipRoutingClient

PhoneNumbersClient

Pesquisar números de telefone disponíveis

Use o método beginSearchAvailablePhoneNumbers para pesquisar números de telefone e reserve-os. Os números de telefone retornados são reservados por 15 minutos e podem ser comprados durante esse período fornecendo a searchId ao método beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers é uma operação de longa execução e retorna um sondador.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const searchResults = await searchPoller.pollUntilDone();
console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
console.log(`searchId: ${searchResults.searchId}`);

Use o método beginPurchasePhoneNumbers para comprar os números de telefone de sua pesquisa. Os números de telefone comprados serão atribuídos ao recurso dos Serviços de Comunicação usado ao iniciar o cliente. O searchId retornado de beginSearchAvailablePhoneNumbers é necessário.

beginPurchasePhoneNumbers é uma operação de longa execução e retorna um sondador.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const { searchId, phoneNumbers } = await searchPoller.pollUntilDone();

const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumbers[0]}`);

Liberar um número de telefone comprado

Use o método beginReleasePhoneNumber para liberar um número de telefone comprado anteriormente. Os números de telefone liberados não serão mais associados ao recurso dos Serviços de Comunicação e não estarão disponíveis para uso com outras operações (por exemplo. SMS) do recurso. O número de telefone que está sendo liberado é necessário.

beginReleasePhoneNumber é uma operação de longa execução e retorna um sondador.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToRelease = "<phone-number-to-release>";

const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");

Atualizar recursos de número de telefone

Use o método beginUpdatePhoneNumberCapabilities para atualizar os recursos de um número de telefone comprado. Os números de telefone podem ser configurados para dar suporte a chamadas de entrada e/ou de saída e sms ou nenhum deles.

beginUpdatePhoneNumberCapabilities é uma operação de longa execução e retorna um sondador.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  PhoneNumberCapabilitiesRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToUpdate = "<phone-number-to-update>";

// This will update phone number to send and receive sms, but only send calls.
const updateRequest: PhoneNumberCapabilitiesRequest = {
  sms: "inbound+outbound",
  calling: "outbound",
};

const updatePoller = await client.beginUpdatePhoneNumberCapabilities(
  phoneNumberToUpdate,
  updateRequest,
);

// Update is underway.
const { capabilities } = await updatePoller.pollUntilDone();
console.log(`These are the update capabilities: ${capabilities}`);

Obter um número de telefone comprado

Use o método getPurchasedPhoneNumber para obter informações sobre um número de telefone comprado. Essas informações incluem o tipo, os recursos, o custo e a data de compra do número de telefone.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToGet = "<phone-number-to-get>";

const phoneNumber = await client.getPurchasedPhoneNumber(phoneNumberToGet);

console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);

Listar números de telefone comprados

Use o método listPurchasedPhoneNumbers para percorrer todos os números de telefone comprados.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumbers = client.listPurchasedPhoneNumbers();

for await (const phoneNumber of phoneNumbers) {
  console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
  console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);
}

SipRoutingClient

Recuperar troncos SIP e rotas

Obtenha a lista de troncos ou rotas configurados no momento.

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

const trunks = client.listTrunks();
const routes = client.listRoutes();
for await (const trunk of trunks) {
  console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
}

for await (const route of routes) {
  console.log(`Route ${route.name} with pattern ${route.numberPattern}`);
  console.log(`Route's trunks: ${route.trunks?.join()}`);
}

Substituir troncos SIP e rotas

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

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.setTrunks([
  {
    fqdn: "sbc.one.domain.com",
    sipSignalingPort: 1234,
  },
  {
    fqdn: "sbc.two.domain.com",
    sipSignalingPort: 1234,
  },
]);

await client.setRoutes([
  {
    name: "First Route",
    description: "route's description",
    numberPattern: "^+[1-9][0-9]{3,23}$",
    trunks: ["sbc.one.domain.com"],
  },
  {
    name: "Second Route",
    description: "route's description",
    numberPattern: "^.*$",
    trunks: ["sbc.two.domain.com", "sbc.one.domain.com"],
  },
]);

Recuperar tronco único

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

const trunk = await client.getTrunk("sbc.one.domain.com");
if (trunk) {
  console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
} else {
  console.log("Trunk not found");
}

Definir tronco único

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.setTrunk({
  fqdn: "sbc.one.domain.com",
  sipSignalingPort: 4321,
});

Excluir tronco único

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.deleteTrunk("sbc.one.domain.com");

Solucionando problemas

Log

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode examinar os documentos do pacote @azure/agente.

Próximas etapas

Examine os exemplos de diretório para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.