Compartir a través de

Biblioteca cliente de Administración de comunicaciones de Azure para JavaScript: versión 1.0.0-beta.3

  • Artículo

La biblioteca de administración se usa para administrar usuarios y tokens para Azure Communication Services. Esta biblioteca también proporciona funcionalidades para la administración de números de teléfono.

Los números de teléfono adquiridos pueden tener muchas funcionalidades, según el país, el tipo de número y el plan de teléfono. Algunos ejemplos de funcionalidades son el uso entrante y saliente de SMS, el uso entrante y saliente de RTC. Los números de teléfono también se pueden asignar a un bot a través de una dirección URL de webhook.

Introducción

Requisitos previos

Instalación de

npm install @azure/communication-administration

Conceptos clave

Clientes

El paquete de administración expone dos clientes. CommunicationIdentityClient Proporciona métodos para administrar usuarios y sus tokens. PhoneNumberAdministrationClient Proporciona métodos para administrar los planes de teléfono y los números.

Introducción a los planes telefónicos

Los planes telefónicos vienen en dos tipos; Geográfico y gratuito. Los planes telefónicos geográficos son planes de teléfono asociados a una ubicación, cuyos códigos de área de números de teléfono están asociados con el código de área de una ubicación geográfica. Toll-Free planes de teléfono son planes de teléfono no asociados. Por ejemplo, en estados Unidos, los números gratuitos pueden tener códigos de área como 800 o 888.

Todos los planes telefónicos geográficos dentro del mismo país se agrupan en un grupo de planes de teléfono con un tipo de número de teléfono geográfico. Todos los Toll-Free planes telefónicos dentro del mismo país se agrupan en un grupo de planes telefónicos.

Búsqueda y adquisición de números

Los números de teléfono se pueden buscar a través de la API de creación de búsqueda proporcionando un identificador de plan de teléfono, un código de área y una cantidad de números de teléfono. La cantidad proporcionada de números de teléfono se reservará durante diez minutos. Esta búsqueda de números de teléfono se puede cancelar o comprar. Si se cancela la búsqueda, los números de teléfono estarán disponibles para otros usuarios. Si se compra la búsqueda, los números de teléfono se adquieren para los recursos de Azure.

Configuración y asignación de números

Los números de teléfono se pueden asignar a una dirección URL de devolución de llamada a través de la API de configuración de números. Como parte de la configuración, necesitará un número de teléfono adquirido, una dirección URL de devolución de llamada y un identificador de aplicación.

Ejemplos

Authentication

Puede obtener una clave o una cadena de conexión del recurso de Communication Services en Azure Portal. Una vez que tenga una clave, puede autenticar CommunicationIdentityClient y PhoneNumberAdministrationClient con cualquiera de los métodos siguientes:

Crear KeyCredential con AzureKeyCredential antes de inicializar el cliente

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

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

Uso de una cadena de conexión

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

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

Si usa una clave para inicializar el cliente, también deberá proporcionar el punto de conexión adecuado. Puede obtener este punto de conexión del recurso de Communication Services en Azure Portal.

Uso

CommunicationIdentityClient

Creación de una instancia de CommunicationIdentityClient

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

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Creación de un nuevo usuario

Use el createUser método para crear un nuevo usuario.

const user = await client.createUser();

Creación y actualización de un token de usuario

Use el issueToken método para emitir o actualizar un token para un usuario existente. El método también toma una lista de ámbitos de token de comunicación. Entre las opciones de ámbito se incluyen:

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

Para actualizar el token de usuario, emita otro token con el mismo usuario.

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

Revocar tokens para un usuario

Use el revokeTokens método para revocar todos los tokens emitidos de un usuario.

await client.revokeTokens(user);

revokeTokens toma un segundo argumento opcional, tokensValidFrom. Si se proporciona esta fecha, revokeTokens revocará todos los tokens emitidos antes de ella. De lo contrario, se revocarán todos los tokens.

Eliminar un usuario

Use el deleteUser método para eliminar un usuario.

await client.deleteUser(user);

PhoneNumberAdministrationClient

Creación de una instancia de PhoneNumberAdministrationClient

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

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Obtención de países

Use el listSupportedCountries método para obtener una lista de los países admitidos.

const countries = await client.listSupportedCountries();

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

Obtención de grupos de planes de teléfono

Los grupos de planes telefónicos vienen en dos tipos, Geográfico y Gratuito. Use el listPhonePlanGroups método para obtenerlos.

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

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

Obtención de opciones de ubicación

En el caso de los planes telefónicos geográficos, puede consultar las ubicaciones geográficas disponibles. Las opciones de ubicaciones se estructuran como la jerarquía geográfica de un país. Por ejemplo, Estados Unidos tiene estados y dentro de cada estado son ciudades.

Use el getPhonePlanLocationOptions método para obtener las opciones de una ubicación.

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

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

Obtención de códigos de área

La captura de códigos de área para planes telefónicos geográficos requerirá las consultas de opciones de ubicación establecidas. Debe incluir la cadena de ubicaciones geográficas que atraviesan el objeto de opciones de ubicación devuelto por .getPhonePlanLocationOptions

Use el getAreaCodes método para obtener los códigos de área de los planes telefónicos geográficos.

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

Reservar números de teléfono para la compra

Use el beginReservePhoneNumbers método para buscar números de teléfono y reservarlos. Se trata de una operación de ejecución 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 obtener los resultados de la reserva, use el pollUntilDone método en el sondeo que creó.

const phoneNumberReservation = await reservePoller.pollUntilDone();

Puede cancelar el sondeo y la reserva llamando al cancelOperation método en el sondeo que creó.

await reservePoller.cancelOperation();

Comprar números de teléfono de una reserva

Use el beginPurchasePhoneNumbers método para comprar los números de teléfono de la reserva. Se requiere el reservationId valor devuelto de beginReservePhoneNumbers . beginPurchasePhoneNumbers también es una operación de larga duración.

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

Para obtener los resultados de la compra, use el pollUntilDone método en el sondeo de compra que creó.

const results = await purchasePoller.pollUntilDone();

Solución de problemas

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones