Biblioteca cliente de números de teléfono de comunicación de Azure para JavaScript: versión 1.3.0

La biblioteca de números de teléfono proporciona funcionalidades para la administración de números de teléfono.

Los números de teléfono comprados pueden tener muchas funcionalidades, según el país, el tipo de número y el tipo de asignación. Algunos ejemplos de funcionalidades son el uso entrante y saliente de SMS, el uso de entrada y salida 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.

Empezar

Prerrequisitos

• Una suscripción de Azure .
• Un recurso de Communication Services existente. Si necesita crear el recurso, puede usar el de Azure Portal de, el azure PowerShello la CLI de Azure .

Instalar

npm install @azure/communication-phone-numbers

Compatibilidad con exploradores

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

Conceptos clave

Este SDK proporciona funcionalidad para administrar fácilmente números de direct offer y direct routing.

Los números de direct offer vienen en dos tipos: geográfico y gratuito. Los planes de teléfono geográfico 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. Se administran mediante el PhoneNumbersClient

La característica direct routing permite conectar la infraestructura de telefonía existente a ACS. La configuración se administra mediante el SipRoutingClient, que proporciona métodos para configurar troncos SIP y reglas de enrutamiento de voz, con el fin de controlar correctamente las llamadas de la subred de telefonía.

Cliente de números de teléfono

Tipos de números de teléfono

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

Todos los números de teléfono geográficos 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 números de teléfono Toll-Free dentro del mismo país se agrupan en un grupo de planes telefónicos.

Buscar y adquirir números

Los números de teléfono se pueden buscar a través de la API de creación de búsquedas proporcionando un tipo de número de teléfono (geográfico o gratuito), tipo de asignación (persona o aplicación), funcionalidades de llamadas y sms, código de área y cantidad de números de teléfono. La cantidad proporcionada de números de teléfono se reservará durante 15 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 el recurso de Azure.

Configuración de números de teléfono

Los números de teléfono pueden tener una combinación de funcionalidades. Se pueden configurar para admitir llamadas entrantes o salientes, o tampoco si no usará el número de teléfono para llamar. Lo mismo se aplica a las funcionalidades de sms.

Es importante tener en cuenta el tipo de asignación de su número de teléfono. Algunas funcionalidades están restringidas a un tipo de asignación determinado.

Cliente de enrutamiento SIP

La característica de enrutamiento directo permite conectar la infraestructura de telefonía proporcionada por el cliente a los recursos de comunicación de Azure. Para configurar correctamente la configuración de enrutamiento, el cliente debe proporcionar la configuración del tronco SIP y las reglas de enrutamiento SIP para las llamadas. El cliente de enrutamiento SIP proporciona la interfaz necesaria para establecer esta configuración.

Cuando se realiza una llamada, el sistema intenta coincidir con el número de destino con patrones de número regex de rutas definidas. Se seleccionará la primera ruta para que coincida con el número. El orden de coincidencia de expresiones regulares es el mismo que el orden de las rutas en la configuración, por lo tanto, el orden de las rutas importa. Una vez que una ruta coincide, la llamada se enruta al primer tronco de la lista de troncos de la ruta. Si el tronco no está disponible, se selecciona el siguiente tronco de la lista.

Ejemplos

Autenticación

Para crear un objeto de cliente para acceder a la API de Communication Services, necesitará un connection string o el endpoint del recurso de Communication Services y un credential. El cliente de números de teléfono puede usar credenciales de Azure Active Directory o una credencial de clave de API para autenticarse.

Puede obtener una clave o una cadena de conexión del recurso de Communication Services en el Azure Portal. También puede encontrar el punto de conexión del recurso de Communication Services en Azure Portal.

Una vez que tenga una clave, puede autenticar al cliente con cualquiera de los métodos siguientes:

Uso de una cadena de conexión

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

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

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

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

Uso de una clave de acceso con AzureKeyCredential

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. Una vez que tenga una clave y un punto de conexión, puede autenticarse con el código siguiente:

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

import { AzureKeyCredential } from "@azure/core-auth";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new AzureKeyCredential("<key-from-resource>");
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

Uso de una credencial de Azure Active Directory

La autenticación de cadena de conexión se usa en la mayoría de los ejemplos, pero también puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure . Para usar el proveedor de de DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el paquete de @azure/identity:

npm install @azure/identity

El paquete @azure/identity proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. El LÉAME para @azure/identity proporciona más detalles y ejemplos para empezar.

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

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

Uso

En las secciones siguientes se proporcionan fragmentos de código que cubren algunas de las tareas comunes mediante el cliente de números de teléfono de Azure Communication Services. Los escenarios que se tratan aquí constan de:

PhoneNumbersClient

• Buscar números de teléfono disponibles
• Comprar números de teléfono de un de búsqueda
• Liberar un número de teléfono comprado
• Actualizar funcionalidades de número de teléfono
• Obtener un número de teléfono comprado
• Lista de números de teléfono comprados

SipRoutingClient

• recuperar troncos SIP y rutas
• reemplazar troncos SIP y rutas
• Recuperar de tronco único
• Establecer de tronco único
• Eliminar de tronco único

PhoneNumbersClient

Buscar números de teléfono disponibles

Use el método beginSearchAvailablePhoneNumbers para buscar números de teléfono y reservarlos. Los números de teléfono devueltos se reservan durante 15 minutos y se pueden comprar durante este período proporcionando el searchId al método beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers es una operación de larga duración y devuelve un sondeo.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  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 = await searchPoller.pollUntilDone();
console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
console.log(`searchId: ${searchResults.searchId}`);

Comprar números de teléfono de una búsqueda

Use el método beginPurchasePhoneNumbers para comprar los números de teléfono de la búsqueda. Los números de teléfono comprados se asignarán al recurso de Communication Services que se usa al iniciar el cliente. Se requiere el searchId devuelto de beginSearchAvailablePhoneNumbers.

beginPurchasePhoneNumbers es una operación de larga duración y devuelve un sondeo.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  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 } = await searchPoller.pollUntilDone();

const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumbers[0]}`);

Liberar un número de teléfono comprado

Use el método beginReleasePhoneNumber para liberar un número de teléfono comprado previamente. Los números de teléfono publicados ya no se asociarán con el recurso de Communication Services y no estarán disponibles para su uso con otras operaciones (por ejemplo, SMS) del recurso. Se requiere el número de teléfono que se está liberando.

beginReleasePhoneNumber es una operación de larga duración y devuelve un sondeo.

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

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToRelease = "<phone-number-to-release>";

const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");

Actualización de las funcionalidades del número de teléfono

Use el método beginUpdatePhoneNumberCapabilities para actualizar las funcionalidades de un número de teléfono adquirido. Los números de teléfono se pueden configurar para admitir llamadas entrantes o salientes y sms, o tampoco.

beginUpdatePhoneNumberCapabilities es una operación de larga duración y devuelve un sondeo.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  PhoneNumberCapabilitiesRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToUpdate = "<phone-number-to-update>";

// This will update phone number to send and receive sms, but only send calls.
const updateRequest: PhoneNumberCapabilitiesRequest = {
  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}`);

Obtener un número de teléfono comprado

Use el método getPurchasedPhoneNumber para obtener información sobre un número de teléfono comprado. Esta información incluye el tipo, las funcionalidades, el costo y la fecha de compra del número de teléfono.

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

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

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

Enumerar números de teléfono comprados

Use el método listPurchasedPhoneNumbers para paginar todos los números de teléfono comprados.

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

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumbers = 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}`);
}

SipRoutingClient

Recuperación de troncos SIP y rutas

Obtenga la lista de troncos o rutas configurados actualmente.

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

const trunks = client.listTrunks();
const routes = client.listRoutes();
for await (const trunk of trunks) {
  console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
}

for await (const route of routes) {
  console.log(`Route ${route.name} with pattern ${route.numberPattern}`);
  console.log(`Route's trunks: ${route.trunks?.join()}`);
}

Reemplazar troncos SIP y rutas

Reemplace la lista de troncos o rutas configurados actualmente por nuevos valores.

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.setTrunks([
  {
    fqdn: "sbc.one.domain.com",
    sipSignalingPort: 1234,
  },
  {
    fqdn: "sbc.two.domain.com",
    sipSignalingPort: 1234,
  },
]);

await client.setRoutes([
  {
    name: "First Route",
    description: "route's description",
    numberPattern: "^+[1-9][0-9]{3,23}$",
    trunks: ["sbc.one.domain.com"],
  },
  {
    name: "Second Route",
    description: "route's description",
    numberPattern: "^.*$",
    trunks: ["sbc.two.domain.com", "sbc.one.domain.com"],
  },
]);

Recuperación del tronco único

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

const trunk = await client.getTrunk("sbc.one.domain.com");
if (trunk) {
  console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
} else {
  console.log("Trunk not found");
}

Establecimiento de un tronco único

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.setTrunk({
  fqdn: "sbc.one.domain.com",
  sipSignalingPort: 4321,
});

Eliminar tronco único

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.deleteTrunk("sbc.one.domain.com");

Solución de problemas

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Pasos siguientes

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

Contribuyendo

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

Proyectos relacionados

• SDK de Microsoft Azure para JavaScript