Compartir a través de

Biblioteca cliente de números de teléfono de Comunicación de Azure para JavaScript: versión 1.0.0

  • Artículo

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 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-phone-numbers

Compatibilidad con exploradores

Paquete de JavaScript

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

Conceptos clave

El paquete de números de teléfono expone el PhoneNumbersClient que proporciona métodos para administrar números de teléfono.

Tipos de número 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 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.

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 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.

Ejemplos

Authentication

Para crear un objeto de cliente para acceder a la API de Communication Services, necesitará o connection string el endpoint de su recurso de Communication Services y .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 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 autenticarse PhoneNumbersClient 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);

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

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 DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el @azure/identity paquete:

npm install @azure/identity

El @azure/identity paquete proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. El archivo 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";

let credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<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 Azure Communication Services. Los escenarios que se tratan aquí constan de:

Búsqueda de los números de teléfono disponibles

Use el beginSearchAvailablePhoneNumbers método 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 al searchIdbeginPurchasePhoneNumbers método .

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

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

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

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

main();

Use el beginPurchasePhoneNumbers método 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 valor devuelto de beginSearchAvailablePhoneNumbers .

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

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

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

async function main() {
  const searchRequest = {
    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 } = searchPoller.pollUntilDone();

  const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

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

main();

Liberar un número de teléfono comprado

Use el beginReleasePhoneNumber método para liberar un número de teléfono comprado previamente. Los números de teléfono publicados ya no se asociarán al 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 va a liberar.

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

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

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

async function main() {
  const phoneNumberToRelease = "<phone-number-to-release>";

  const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

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

main();

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

Use el beginUpdatePhoneNumberCapabilities método para actualizar las funcionalidades de un número de teléfono comprado. 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 { PhoneNumbersClient } from "@azure/communication-phone-numbers";

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

async function main() {
  const phoneNumberToUpdate = "<phone-number-to-update>";

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

main();

Obtener un número de teléfono comprado

Use el getPurchasedPhoneNumber método 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 { PhoneNumbersClient } from "@azure/communication-phone-numbers";

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

async main function() {
  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}`);
}

main();

Enumerar números de teléfono comprados

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

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

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

async main function() {
  const phoneNumbers = await 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}`);
  }
}

main();

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