Biblioteca de clientes da Administração de Comunicação do Azure para JavaScript – versão 1.0.0-beta.3

  • Artigo

A biblioteca de administração é usada para gerenciar usuários e tokens para Serviços de Comunicação do Azure. Essa biblioteca também fornece recursos para administração de números de telefone.

Os números de telefone adquiridos podem vir com muitas funcionalidades, dependendo do país, do tipo de número e do plano telefônico. 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

Instalando o

npm install @azure/communication-administration

Principais conceitos

Clientes

O pacote de administração expõe dois clientes. O CommunicationIdentityClient fornece métodos para gerenciar usuários e seus tokens. O PhoneNumberAdministrationClient fornece métodos para gerenciar planos e números de telefone.

Visão geral dos planos telefônicos

Os planos telefônicos 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 de chamada gratuita podem vir com códigos de área como 800 ou 888.

Todos os planos telefônicos 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 planos telefônicos 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 de pesquisa fornecendo uma ID de plano de telefone, um código de área e uma quantidade de números de telefone. A quantidade fornecida de números de telefone será reservada por dez 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 os recursos do Azure.

Configurando e atribuindo números

Os números de telefone podem ser atribuídos a uma URL de retorno de chamada por meio da API de configuração de número. Como parte da configuração, você precisará de um número de telefone adquirido, uma URL de retorno de chamada e uma ID do aplicativo.

Exemplos

Autenticação

Você pode obter uma chave e/ou uma cadeia de conexão do recurso dos Serviços de Comunicação no Portal do Azure. Depois de ter uma chave, você poderá autenticar o CommunicationIdentityClient e PhoneNumberAdministrationClient com qualquer um dos seguintes métodos:

Criar KeyCredential com AzureKeyCredential antes de inicializar o cliente

import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-administration";

const credential = new AzureKeyCredential(KEY);
const client = new CommunicationIdentityClient(HOST, credential);

Usando uma cadeia de conexão

import { PhoneNumberAdministrationClient } from "@azure/communication-administration";

const connectionString = `endpoint=HOST;accessKey=KEY`;
const client = new CommunicationIdentityClient(connectionString);

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.

Uso

CommunicationIdentityClient

Criando uma instância de CommunicationIdentityClient

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Criando um novo usuário

Use o createUser método para criar um novo usuário.

const user = await client.createUser();

Criando e atualizando um token de usuário

Use o issueToken método para emitir ou atualizar um token para um usuário existente. O método também usa uma lista de escopos de token de comunicação. As opções de escopo incluem:

  • chat (Chat)
  • pstn (Rede telefônica pública comutada)
  • voip (Voz sobre IP)
let { token } = await client.issueToken(user, ["chat"]);

Para atualizar o token de usuário, emita outro token com o mesmo usuário.

{ token } = await client.issueToken(user, ["chat"]);

Revogando tokens para um usuário

Use o revokeTokens método para revogar todos os tokens emitidos de um usuário.

await client.revokeTokens(user);

revokeTokens usa um segundo argumento opcional, tokensValidFrom. Se essa data for fornecida, revokeTokens revogará todos os tokens emitidos antes dela. Caso contrário, todos os tokens serão revogados.

Excluir um usuário

Use o deleteUser método para excluir um usuário.

await client.deleteUser(user);

PhoneNumberAdministrationClient

Criando uma instância de PhoneNumberAdministrationClient

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Obtendo países

Use o listSupportedCountries método para obter uma lista dos países com suporte.

const countries = await client.listSupportedCountries();

for await (const country of countries) {
  console.log(`Country code: ${country.countryCode}`);
  console.log(`Country name: ${country.localizedName}`);
}

Obtendo grupos de planos telefônicos

Os grupos de planos telefônicos vêm em dois tipos, Geográfico e Gratuito. Use o listPhonePlanGroups método para obtê-los.

const countryCode = "US";
const phonePlanGroups = await client.listPhonePlanGroups(countryCode);

for await (const phonePlanGroup of phonePlanGroups) {
  console.log(`Phone plan group id: ${phonePlanGroup.phonePlanGroupId}`);
}

Obtendo opções de localização

Para planos de telefone geográficos, você pode consultar as localizações geográficas disponíveis. As opções de locais são estruturadas como a hierarquia geográfica de um país. Por exemplo, os EUA têm estados e dentro de cada estado estão cidades.

Use o getPhonePlanLocationOptions método para obter as opções de um local.

const { locationOptions } = await client.getPhonePlanLocationOptions({
  countryCode: "US",
  phonePlanGroupId: "phonePlanGroupId",
  phonePlanId: "phonePlanId"
});

console.log(`Got location options for: ${locationOptions.labelId}`);

Obtendo códigos de área

Buscar códigos de área para planos de telefone geográficos exigirá o conjunto de consultas de opções de localização. Você deve incluir a cadeia de localizações geográficas percorrendo o objeto de opções de localização retornado pelo getPhonePlanLocationOptions.

Use o getAreaCodes método para obter os códigos de área para planos de telefone geográficos.

const { primaryAreaCodes } = await client.getAreaCodes({
  locationType: "selection",
  countryCode: "US",
  phonePlanId: "phonePlanId",
  locationOptionsQueries
});

Reservando números de telefone para compra

Use o beginReservePhoneNumbers método para pesquisar números de telefone e reserve-os. Essa é uma operação em execução longa.

const reservePoller = await client.beginReservePhoneNumbers({
    name: "Phone number search 800",
    description: "Search for 800 phone numbers"
    phonePlanIds: ["phone-plan-id-1"],
    areaCode: "800",
    quantity: 3
});

Para obter os resultados da reserva, use o pollUntilDone método no poller que você criou.

const phoneNumberReservation = await reservePoller.pollUntilDone();

Você pode cancelar a sondagem e a reserva chamando o cancelOperation método no sondador que você criou.

await reservePoller.cancelOperation();

Comprar números de telefone de uma reserva

Use o beginPurchasePhoneNumbers método para comprar os números de telefone de sua reserva. O reservationId retornado de beginReservePhoneNumbers é necessário. beginPurchasePhoneNumbers também é uma operação de execução prolongada.

const { reservationId } = phoneNumberReservation;
const purchasePoller = await client.beginPurchasePhoneNumbers(reservationId);

Para obter os resultados da compra, use o pollUntilDone método no sondador de compra que você criou.

const results = await purchasePoller.pollUntilDone();

Solução de problemas

Próximas etapas

Dê uma olhada no 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