Partilhar via

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

  • Artigo

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

Os números de telefone comprados podem ter muitas funcionalidades, consoante o país, o tipo de número e o tipo de atribuição. Exemplos de capacidades são a utilização de entrada e saída de SMS, a utilização de entrada e saída rtPC. Os números de telefone também podem ser atribuídos a um bot através de um URL de webhook.

Introdução

Pré-requisitos

Instalação

npm install @azure/communication-phone-numbers

Browser support (Suporte do browser)

Pacote JavaScript

Para utilizar esta biblioteca de cliente no browser, primeiro tem de utilizar um bundler. Para obter detalhes sobre como fazê-lo, veja a nossa documentação de agrupamento.

Conceitos-chave

O pacote de números de telefone expõe o PhoneNumbersClient que fornece métodos para gerir números de telefone.

Tipos de número de telefone

Os números de telefone são apresentados em dois tipos; Geográfico e gratuito. 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 ser fornecidos com códigos de área como 800 ou 888.

Todos os números de telefone geográficos no mesmo país são agrupados num 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 num grupo de planos telefónicos.

Procurar e adquirir números

Os números de telefone podem ser pesquisados através da API de criação de pesquisa ao fornecer um tipo de número de telefone (geográfico ou gratuito), tipo de atribuição (pessoa ou aplicação), funcionalidades de chamadas e sms, um código de área e uma quantidade de números de telefone. A quantidade fornecida de números de telefone será reservada durante 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 são adquiridos para o recurso do Azure.

Configurar números de telefone

Os números de telefone podem ter uma combinação de capacidades. Podem ser configuradas para suportar chamadas de entrada e/ou de saída, ou nem se não utilizar o número de telefone para efetuar chamadas. O mesmo se aplica às capacidades de SMS.

É importante considerar o tipo de atribuição do seu número de telefone. Algumas capacidades estão restritas a um tipo de atribuição específico.

Exemplos

Autenticação

Para criar um objeto de cliente para aceder à API dos Serviços de Comunicação, precisará de um connection string ou do endpoint recurso dos Serviços de Comunicação e de um credential. O cliente de Números de Telefone pode utilizar credenciais do Azure Active Directory ou uma credencial de chave de API para autenticar.

Pode obter uma chave e/ou cadeia de ligação a partir do recurso dos Serviços de Comunicação no portal do Azure. Também pode encontrar o ponto final do recurso dos Serviços de Comunicação no portal do Azure.

Assim que tiver uma chave, pode autenticar PhoneNumbersClient com qualquer um dos seguintes métodos:

Utilizar uma cadeia de ligação

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

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

Utilizar uma chave de acesso com AzureKeyCredential

Se utilizar uma chave para inicializar o cliente, também terá de fornecer o ponto final adequado. Pode obter este ponto final a partir do recurso dos Serviços de Comunicação no portal do Azure. Assim que tiver uma chave e um ponto final, 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);

Utilizar uma Credencial do Azure Active Directory

A autenticação de cadeia de ligação é utilizada na maioria dos exemplos, mas também pode autenticar com o Azure Active Directory com a biblioteca de Identidade do Azure. Para utilizar o fornecedor DefaultAzureCredential mostrado abaixo ou outros fornecedores 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 credenciais que a sua aplicação pode utilizar para o fazer. O README 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);

Utilização

As secções seguintes fornecem fragmentos de código que abrangem algumas das tarefas comuns com o cliente Azure Communication Services Números de Telefone. Os cenários abordados aqui consistem em:

Procurar números de telefone disponíveis

Utilize o beginSearchAvailablePhoneNumbers método para procurar números de telefone e reservá-los. Os números de telefone devolvidos são reservados durante 15 minutos e podem ser comprados durante este período ao fornecer o searchIdbeginPurchasePhoneNumbers método .

beginSearchAvailablePhoneNumbers é uma operação de execução prolongada e devolve um poller.

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

Utilize o beginPurchasePhoneNumbers método para comprar os números de telefone da pesquisa. Os números de telefone comprados serão atribuídos ao recurso dos Serviços de Comunicação utilizado ao iniciar o cliente. O searchId devolvido de beginSearchAvailablePhoneNumbers é obrigatório.

beginPurchasePhoneNumbers é uma operação de execução prolongada e devolve um poller.

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

Libertar um número de telefone comprado

Utilize o beginReleasePhoneNumber método para libertar um número de telefone comprado anteriormente. Os números de telefone lançados deixarão de estar associados ao recurso dos Serviços de Comunicação e não estarão disponíveis para utilização com outras operações (por exemplo, SMS) do recurso. O número de telefone que está a ser libertado é obrigatório.

beginReleasePhoneNumber é uma operação de execução prolongada e devolve um poller.

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 capacidades de número de telefone

Utilize o beginUpdatePhoneNumberCapabilities método para atualizar as capacidades 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 dos dois.

beginUpdatePhoneNumberCapabilities é uma operação de execução prolongada e devolve um poller.

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

Utilize o getPurchasedPhoneNumber método para obter informações sobre um número de telefone comprado. Estas informações incluem o tipo, capacidades, custo e 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

Utilize o listPurchasedPhoneNumbers método para analisar todos os números de telefone comprados.

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

Resolução de problemas

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Contribuir

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

Impressões