Compartilhar via

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

  • Artigo

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

Os números de telefone adquiridos podem vir com muitos recursos, 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 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

Instalando o

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

O pacote de números de telefone expõe o PhoneNumbersClient que fornece métodos para gerenciar 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 dentro do 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 adquirida, 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 recursos. Eles podem ser configurados para dar suporte a chamadas de entrada e/ou de saída ou também se você não usar o número de telefone para chamada. 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.

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 do endpoint recurso dos Serviços de Comunicação e de 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 uma 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ê poderá autenticar o PhoneNumbersClient 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);

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);

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 @azure/identity pacote:

npm install @azure/identity

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

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

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

Uso

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

Pesquisar números de telefone disponíveis

Use o beginSearchAvailablePhoneNumbers método 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 o searchIdbeginPurchasePhoneNumbers ao método .

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

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

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

async function main() {
  const searchRequest = {
    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 = searchPoller.pollUntilDone();
  console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
  console.log(`searchId: ${searchResults.searchId}`);
}

main();

Use o beginPurchasePhoneNumbers método para comprar os números de telefone de sua pesquisa. Os números de telefone adquiridos 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 execução longa e retorna um sondador.

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

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

async function main() {
  const searchRequest = {
    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 } = searchPoller.pollUntilDone();

  const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

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

main();

Liberar um número de telefone comprado

Use o beginReleasePhoneNumber método 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 execução longa e retorna um sondador.

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

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

async function main() {
  const phoneNumberToRelease = "<phone-number-to-release>";

  const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

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

main();

Atualizar as funcionalidades do número de telefone

Use o beginUpdatePhoneNumberCapabilities método 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 execução longa e retorna um sondador.

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

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

async function main() {
  const phoneNumberToUpdate = "<phone-number-to-update>";

  // This will update phone number to send and receive sms, but only send calls.
  const updateRequest = {
    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}`);
}

main();

Obter um número de telefone comprado

Use o getPurchasedPhoneNumber método 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 { PhoneNumbersClient } from "@azure/communication-phone-numbers";

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

async main function() {
  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}`);
}

main();

Listar números de telefone comprados

Use o listPurchasedPhoneNumbers método para usar a página em todos os números de telefone adquiridos.

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

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

async main function() {
  const phoneNumbers = await 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}`);
  }
}

main();

Solução de problemas

Próximas etapas

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

Contribuição

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

Impressões