Partilhar via

Biblioteca de cliente do Azure Communication Phone Numbers 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 muitos recursos, dependendo do país, tipo de número e tipo de atribuição. Exemplos de recursos são o uso de entrada e saída de SMS, o uso de entrada e saída de PSTN. Os números de telefone também podem ser atribuídos a um bot através de um URL webhook.

Primeiros passos

Pré-requisitos

  • Uma assinatura do Azure.
  • Um recurso de Serviços de Comunicação existente. Se precisar criar o recurso, você pode usar o do Portal doAzure, o doAzure PowerShell ou o da CLI doAzure.

Instalação

npm install @azure/communication-phone-numbers

Suporte do navegador

Pacote JavaScript

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

Conceitos-chave

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

Os números direct offer vêm em dois tipos: geográfico e gratuito. Os planos telefónicos geográficos são planos telefónicos associados a uma localização, cujos códigos de área dos 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 à localização. Por exemplo, nos EUA, os 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 adequadamente com chamadas para sua sub-rede de telefonia.

Cliente de números de telefone

Tipos de número de telefone

Os números de telefone são de dois tipos; Geográfica e Toll-Free. Os números de telefone geográficos são números de telefone associados a uma localização, 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 uma localização. Por exemplo, nos EUA, os números gratuitos podem vir com códigos de área como 800 ou 888.

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

Pesquisa e aquisição de números

Os números de telefone podem ser pesquisados através da API de criação de 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. Esta 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.

Configurar números de telefone

Os números de telefone podem ter uma combinação de capacidades. Eles podem ser configurados para suportar chamadas de entrada e/ou saída, ou nenhum deles se você não usar o número de telefone para fazer chamadas. 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 de regex é a mesma que a ordem das rotas em configuração, portanto, a ordem das rotas importa. Quando 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 da endpoint do recurso dos Serviços de Comunicação e de um credential. O cliente de Números de Telefone pode usar credenciais do Azure Ative Directory ou uma credencial de chave de API para autenticar.

Você pode obter uma chave e/ou cadeia de conexão do seu recurso Serviços de Comunicação no Portal do Azure. Você também pode encontrar o ponto de extremidade para seu recurso de 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 seu recurso de Serviços de Comunicação em Portal do Azure. Depois de ter uma chave e um ponto de extremidade, você pode 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 Ative Directory

A autenticação de cadeia de conexão é usada na maioria dos exemplos, mas você também pode autenticar com o Azure Ative Directory usando a biblioteca de Identidade do Azure. Para usar o provedor de 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 credenciais 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);

Utilização

As seções a seguir fornecem trechos 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 aqui abordados consistem em:

Números de telefoneCliente

SipRoutingClient

Números de telefoneCliente

Pesquisar números de telefone disponíveis

Use o método beginSearchAvailablePhoneNumbers para procurar números de telefone e reservá-los. Os números de telefone devolvidos são reservados por 15 minutos e podem ser adquiridos durante este período, fornecendo o searchId para o método beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers é uma operação de longa duração e retorna um poller.

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 da sua pesquisa. Os números de telefone adquiridos serão atribuídos ao recurso Serviços de Comunicação usado ao iniciar o cliente. O searchId devolvido de beginSearchAvailablePhoneNumbers é obrigatório.

beginPurchasePhoneNumbers é uma operação de longa duração e retorna um poller.

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 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 duração e retorna um poller.

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 suportar chamadas de entrada e/ou saída e sms, ou nenhum.

beginUpdatePhoneNumberCapabilities é uma operação de longa duração e retorna um poller.

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 e rotas SIP

Obtenha a lista de troncos ou rotas configurados atualmente.

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

Substitua troncos e rotas SIP

Substitua a lista de troncos ou rotas configurados atualmente 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");

Solução de problemas

Registo

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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

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

Próximos passos

Por favor, dê uma olhada no exemplos diretório para obter exemplos detalhados sobre como usar esta biblioteca.

Contribuição

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