Biblioteca cliente de números de teléfono de Comunicación de Azure para Java: versión 1.1.7
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 APIDocumentació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.NONEPhoneNumberCapabilityValue.INBOUNDPhoneNumberCapabilityValue.OUTBOUNDPhoneNumberCapabilityValue.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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de