Biblioteca de cliente da Administração de Comunicações do Azure para JavaScript – versão 1.0.0-beta.3
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
- Uma subscrição do Azure.
- Um recurso existente do Communication Services. Se precisar de criar o recurso, pode utilizar o Portal do Azure ou a CLI do Azure.
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 CommunicationIdentityClient
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);
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.
Projetos relacionados
Azure SDK for JavaScript