Biblioteca cliente de números de teléfono de Comunicación de Azure para .NET: versión 1.1.0

Artículo
04/03/2023

Los números de teléfono de comunicación de Azure administran números de teléfono para Azure Communication Services.

Código | fuente | Documentación del producto Muestras

Introducción

Instalar el paquete

Instale la biblioteca cliente de números de teléfono de Comunicación de Azure para .NET con NuGet:

dotnet add package Azure.Communication.PhoneNumbers

Prerrequisitos

Necesita una suscripción de Azure y un recurso de Communication Service para usar este paquete.

Para crear un servicio de comunicación, puede usar Azure Portal, la Azure PowerShell o la biblioteca cliente de administración de .NET.

Conceptos clave

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

Los direct offer números vienen en dos tipos: Geográfico y Gratuito. Los planes de teléfono 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 al 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 PhoneNumbersClient

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

Autenticar el cliente

Los clientes se pueden autenticar mediante la cadena de conexión adquirida desde un recurso de comunicación de Azure en Azure Portal.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);

// Get a connection string to Azure Communication resource.
var connectionString = "<connection_string>";
var client = new SipRoutingClient(connectionString);

Los clientes también tienen la opción de autenticarse con la autenticación de Azure Active Directory. Para más información sobre este tema, consulte Identidad de Azure.

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new SipRoutingClient(endpoint, tokenCredential);

Cliente de números de teléfono

Introducción a los tipos de números de teléfono

Los números de teléfono vienen en dos tipos: geográfico y gratuito. Los planes de teléfono 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 al 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 de teléfono 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 planes telefónicos Toll-Free dentro del mismo país se agrupan en un grupo de planes telefónicos.

Buscar, comprar y liberar números de teléfono

Los números de teléfono se pueden buscar a través de la API de creación de búsquedas proporcionando un código de área, cantidad de números de teléfono, tipo de aplicación, tipo de número de teléfono y funcionalidades. La cantidad proporcionada de números de teléfono se reservará durante diez minutos y se puede comprar en este momento. Si no se compra la búsqueda, los números de teléfono estarán disponibles para otros después de diez minutos. Si se compra la búsqueda, los números de teléfono se adquieren para los recursos de Azure.

Los números de teléfono también se pueden publicar mediante la API de versión.

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 hacer coincidir 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 regex es el mismo que el orden de las rutas en la configuración, por lo que el orden de las rutas importa. Una vez que se hace coincidir una ruta, 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.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Ejemplos

PhoneNumbersClient

Crear un phoneNumbersClient

Para crear una nuevaPhoneNumbersClient, necesita una cadena de conexión al recurso Azure Communication Services que puede obtener de Azure Portal una vez que haya creado el recurso.

Puede establecer connectionString en función de una variable de entorno, una configuración o cualquier forma que funcione para la aplicación.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);

Buscar números de teléfono

Los números de teléfono deben buscarse para poder comprarse. La búsqueda es una operación de larga duración que puede iniciarse mediante StartSearchAvailablePhoneNumbers una función que devuelve un SearchAvailablePhoneNumbersOperation objeto . SearchAvailablePhoneNumbersOperation se puede usar para actualizar el estado de la operación y para comprobar si hay integridad.

var capabilities = new PhoneNumberCapabilities(calling: PhoneNumberCapabilityType.None, sms: PhoneNumberCapabilityType.Outbound);

var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync(countryCode, PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities);
await searchOperation.WaitForCompletionAsync();

Compra de números de teléfono

Los números de teléfono se pueden adquirir mediante la compra de una búsqueda.

var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();

Enumerar números de teléfono comprados

Puede enumerar todos los números de teléfono que se han comprado para el recurso.

var purchasedPhoneNumbers = client.GetPurchasedPhoneNumbersAsync();

await foreach (var phoneNumber in purchasedPhoneNumbers)
{
    Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}, monthly cost: {phoneNumber.Cost}");
}

Liberar números de teléfono

Si ya no necesita un número de teléfono, puede liberarlo.

var purchasedPhoneNumber = "<purchased_phone_number>";
var releaseOperation = await client.StartReleasePhoneNumberAsync(purchasedPhoneNumber);
await releaseOperation.WaitForCompletionResponseAsync();
await WaitForCompletionResponseAsync(releaseOperation);

SipRoutingClient

Recuperación de troncos SIP y rutas

Obtenga la lista de troncos o rutas configurados actualmente.

var trunksResponse = await client.GetTrunksAsync();
var routesResponse = await client.GetRoutesAsync();

Reemplazar troncos SIP y rutas

Reemplace la lista de troncos o rutas configurados actualmente.

// The service will not allow trunks that are used in any of the routes to be deleted, therefore first set the routes as empty list, and then update the routes.
var newTrunks = "<new_trunks_list>";
var newRoutes = "<new_routes_list>";
await client.SetRoutesAsync(new List<SipTrunkRoute>());
await client.SetTrunksAsync(newTrunks);
await client.SetRoutesAsync(newRoutes);

Administración de un único tronco

Los troncos SIP se pueden administrar por separado mediante para SipRoutingClient recuperar, establecer o eliminar un único tronco.

Recuperación de un único tronco

// Get trunk object, based on it's FQDN.
var fqdnToRetrieve = "<fqdn>";
var trunkResponse = await client.GetTrunkAsync(fqdnToRetrieve);

Establecer tronco único

// Set function will either modify existing item or add new item to the collection.
// The trunk is matched based on it's FQDN.
var trunkToSet = "<trunk_to_set>";
await client.SetTrunkAsync(trunkToSet);

Eliminar tronco único

// Deletes trunk with supplied FQDN.
var fqdnToDelete = "<fqdn>";
await client.DeleteTrunkAsync(fqdnToDelete);

Solución de problemas

Pasos siguientes

Más información sobre la administración de números de teléfono

Más información sobre el enrutamiento directo

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Compartir a través de