Biblioteca cliente de números de teléfono de Comunicación de Azure para Java: versión 1.1.7

Artículo
10/21/2023

El paquete 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 plan de teléfono. Algunos ejemplos de funcionalidades son el uso entrante y saliente de SMS, la llamada al uso entrante y saliente. Los números de teléfono también se pueden asignar a un bot a través de una dirección URL de webhook.

Código | fuentePaquete (Maven) | Documentación | de referencia de API Documentación del producto

Introducción

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Kit de desarrollo de Java (JDK), versión 8 o posterior.
Apache Maven.
Un recurso de Communication Services implementado. Puede usar Azure Portal o el Azure PowerShell para configurarlo.

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte el archivo Léame bom del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-phonenumbers</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si desea depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-phonenumbers</artifactId>
  <version>1.1.7</version>
</dependency>

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.

Inicialización del cliente

Los clientes se pueden inicializar mediante la autenticación de Azure Active Directory.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

También es posible usar el punto de conexión y la clave de acceso desde el recurso de comunicación para autenticarse.

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

Como alternativa, puede proporcionar toda la cadena de conexión mediante la función connectionString() del cliente en lugar de proporcionar el punto de conexión y la clave de acceso.

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.

Buscar y comprar y liberar 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 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 podrá 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 compran 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 llega la 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 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.

Ejemplos

PhoneNumbersClient

Obtener número de teléfono comprado

Obtiene el número de teléfono comprado especificado.

PurchasedPhoneNumber phoneNumber = phoneNumberClient.getPurchasedPhoneNumber("+18001234567");
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

Obtener todos los números de teléfono comprados

Enumera todos los números de teléfono comprados.

PagedIterable<PurchasedPhoneNumber> phoneNumbers = createPhoneNumberClient().listPurchasedPhoneNumbers(Context.NONE);
PurchasedPhoneNumber phoneNumber = phoneNumbers.iterator().next();
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

Operaciones de larga duración

El cliente de número de teléfono admite una variedad de operaciones de larga duración que permiten un tiempo de sondeo indefinido a las funciones que se enumeran a continuación.

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

Busque números de teléfono disponibles proporcionando el código de área, el tipo de asignación, las capacidades del número de teléfono, el tipo de número de teléfono y la cantidad. El resultado de la búsqueda se puede usar para comprar los números. Tenga en cuenta que proporcionar el código de área para el tipo de número de teléfono gratuito es opcional.

PhoneNumbersClient phoneNumberClient = createPhoneNumberClient();
PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities()
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);
PhoneNumberSearchOptions searchOptions = new PhoneNumberSearchOptions().setAreaCode("800").setQuantity(1);

SyncPoller<PhoneNumberOperation, PhoneNumberSearchResult> poller = phoneNumberClient
    .beginSearchAvailablePhoneNumbers("US", PhoneNumberType.TOLL_FREE, PhoneNumberAssignmentType.APPLICATION, capabilities, searchOptions, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();
String searchId = "";

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PhoneNumberSearchResult searchResult = poller.getFinalResult();
    searchId = searchResult.getSearchId();
    System.out.println("Searched phone numbers: " + searchResult.getPhoneNumbers());
    System.out.println("Search expires by: " + searchResult.getSearchExpiresBy());
    System.out.println("Phone number costs:" + searchResult.getCost().getAmount());
}

Compra de números de teléfono

El resultado de la búsqueda de números de teléfono es un valor de PhoneNumberSearchResult. Esto se puede usar para obtener los detalles de los números y los números de compra pasando a searchId la API de números de compra.

PollResponse<PhoneNumberOperation> purchaseResponse =
    phoneNumberClient.beginPurchasePhoneNumbers(searchId, Context.NONE).waitForCompletion();
System.out.println("Purchase phone numbers is complete: " + purchaseResponse.getStatus());

Descarte de un número de teléfono

Libera un número de teléfono comprado.

PollResponse<PhoneNumberOperation> releaseResponse =
    phoneNumberClient.beginReleasePhoneNumber("+18001234567", Context.NONE).waitForCompletion();
System.out.println("Release phone number is complete: " + releaseResponse.getStatus());

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

Novedades funcionalidades de número de teléfono para llamadas y SMS a uno de:

PhoneNumberCapabilityValue.NONE
PhoneNumberCapabilityValue.INBOUND
PhoneNumberCapabilityValue.OUTBOUND
PhoneNumberCapabilityValue.INBOUND_OUTBOUND

PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities();
capabilities
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);

SyncPoller<PhoneNumberOperation, PurchasedPhoneNumber> poller = phoneNumberClient.beginUpdatePhoneNumberCapabilities("+18001234567", capabilities, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PurchasedPhoneNumber phoneNumber = poller.getFinalResult();
    System.out.println("Phone Number Calling capabilities: " + phoneNumber.getCapabilities().getCalling()); //Phone Number Calling capabilities: inbound
    System.out.println("Phone Number SMS capabilities: " + phoneNumber.getCapabilities().getSms()); //Phone Number SMS capabilities: inbound+outbound
}

SipRoutingClient

Recuperación de troncos SIP y rutas

Obtenga la lista de troncos o rutas configurados actualmente.

PagedIterable<SipTrunk> trunks = sipRoutingClient.listTrunks();
PagedIterable<SipTrunkRoute> routes = sipRoutingClient.listRoutes();
for (SipTrunk trunk : trunks) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
}
for (SipTrunkRoute route : routes) {
    System.out.println("Route name: " + route.getName());
    System.out.println("Route description: " + route.getDescription());
    System.out.println("Route number pattern: " + route.getNumberPattern());
    System.out.println("Route trunks: " + String.join(",", route.getTrunks()));
}

Reemplazar troncos SIP y rutas

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

sipRoutingClient.setTrunks(asList(
    new SipTrunk("<first trunk fqdn>", 12345),
    new SipTrunk("<second trunk fqdn>", 23456)
));
sipRoutingClient.setRoutes(asList(
    new SipTrunkRoute("route name1", ".*9").setTrunks(asList("<first trunk fqdn>", "<second trunk fqdn>")),
    new SipTrunkRoute("route name2", ".*").setTrunks(asList("<second trunk fqdn>"))
));

Recuperación de un único tronco

String fqdn = "<trunk fqdn>";
SipTrunk trunk = sipRoutingClient.getTrunk(fqdn);
if (trunk != null) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
} else {
    System.out.println("Trunk not found. " + fqdn);
}

Establecer tronco único

sipRoutingClient.setTrunk(new SipTrunk("<trunk fqdn>", 12345));

Eliminar tronco único

sipRoutingClient.deleteTrunk("<trunk fqdn>");

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.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

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.

Solución de problemas

En curso.

Pasos siguientes

Consulte otras bibliotecas cliente para El servicio de comunicación de Azure

Impresiones

Compartir a través de