Partilhar via

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

  • Artigo

A biblioteca de administração é utilizada para gerir utilizadores e tokens para Azure Communication Services. Esta biblioteca também fornece capacidades para a administração de números de telefone.

Os números de telefone adquiridos podem ter muitas funcionalidades, consoante o país, o tipo de número e o plano telefónico. 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-administration

Conceitos-chave

Clientes

O pacote de administração expõe dois clientes. O CommunicationIdentityClient fornece métodos para gerir os utilizadores e os respetivos tokens. O PhoneNumberAdministrationClient fornece métodos para gerir planos e números de telefone.

Descrição geral dos planos telefónicos

Os planos telefónicos são de dois tipos; Geográfico e gratuito. Os planos de telefone geográficos são planos de telefone associados a uma localização, 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 que não estão associados à localização. Por exemplo, nos EUA, os números gratuitos podem ser fornecidos com códigos de área como 800 ou 888.

Todos os planos 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 planos telefónicos dentro do mesmo país estã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 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 durante dez 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 os recursos do Azure.

Configurar e atribuir números

Os números de telefone podem ser atribuídos a um URL de chamada de retorno através da API de número de configuração. Como parte da configuração, precisará de um número de telefone adquirido, um URL de chamada de retorno e um ID da aplicação.

Exemplos

Autenticação

Pode obter uma chave e/ou cadeia de ligação a partir do recurso dos Serviços de Comunicação no portal do Azure. Assim que tiver uma chave, pode autenticar e CommunicationIdentityClientPhoneNumberAdministrationClient 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);

Utilizar uma cadeia de ligação

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

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

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.

Utilização

CommunicationIdentityClient

Criar uma instância de CommunicationIdentityClient

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

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Criar um novo utilizador

Utilize o createUser método para criar um novo utilizador.

const user = await client.createUser();

Criar e atualizar um token de utilizador

Utilize o issueToken método para emitir ou atualizar um token para um utilizador existente. O método também inclui uma lista de âmbitos de tokens de comunicação. As opções de âmbito incluem:

  • chat (Chat)
  • pstn (Rede telefónica pública comutado)
  • voip (Voice over IP)
let { token } = await client.issueToken(user, ["chat"]);

Para atualizar o token de utilizador, emita outro token com o mesmo utilizador.

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

Revogar tokens para um utilizador

Utilize o revokeTokens método para revogar todos os tokens emitidos de um utilizador.

await client.revokeTokens(user);

revokeTokens utiliza um segundo argumento opcional, tokensValidFrom. Se esta data for fornecida, revokeTokens revogará todos os tokens emitidos antes da mesma. Caso contrário, todos os tokens serão revogados.

Eliminar um utilizador

Utilize o deleteUser método para eliminar um utilizador.

await client.deleteUser(user);

PhoneNumberAdministrationClient

Criar uma instância de PhoneNumberAdministrationClient

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

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Obter países

Utilize o listSupportedCountries método para obter uma lista dos países suportados.

const countries = await client.listSupportedCountries();

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

Obter grupos de planos telefónicos

Os grupos de planos telefónicos são provenientes de dois tipos, Geográficos e Gratuitos. Utilize 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}`);
}

Obter opções de localização

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

Utilize o getPhonePlanLocationOptions método para obter as opções de uma localização.

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

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

Obter códigos de área

A obtenção de códigos de área para planos de telefone geográficos exigirá as consultas de opções de localização definidas. Tem de incluir a cadeia de localizações geográficas que percorre o objeto de opções de localização devolvido pelo getPhonePlanLocationOptions.

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

Reservar números de telefone para compra

Utilize o beginReservePhoneNumbers método para procurar números de telefone e reservá-los. Esta é uma operação de execução prolongada.

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, utilize o pollUntilDone método no poller que criou.

const phoneNumberReservation = await reservePoller.pollUntilDone();

Pode cancelar a consulta e a reserva ao chamar o cancelOperation método no poller que criou.

await reservePoller.cancelOperation();

Comprar números de telefone de uma reserva

Utilize o beginPurchasePhoneNumbers método para comprar os números de telefone da reserva. O reservationId devolvido de beginReservePhoneNumbers é obrigató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, utilize o pollUntilDone método no poller de compra que criou.

const results = await purchasePoller.pollUntilDone();

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