Bibliothèque cliente numéros de téléphone Azure Communication pour Java - version 1.1.7

Article
10/21/2023

Le package de numéros de téléphone fournit des fonctionnalités pour la gestion des numéros de téléphone.

Les numéros de téléphone achetés peuvent être fournis avec de nombreuses fonctionnalités, selon le pays, le type de numéro et le plan téléphonique. Parmi les exemples de fonctionnalités, citons l’utilisation entrante et sortante des SMS, l’appel de l’utilisation entrante et sortante. Les numéros de téléphone peuvent également être attribués à un bot via une URL de webhook.

| Code source Package (Maven) | Documentation de référence sur les | APIDocumentation produit

Prise en main

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Java Development Kit (JDK) version 8 ou ultérieure.
Apache Maven.
Une ressource Communication Services déployée. Vous pouvez utiliser le portail Azure ou le Azure PowerShell pour le configurer.

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL 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>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

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

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Concepts clés

Ce Kit de développement logiciel (SDK) fournit des fonctionnalités permettant de gérer facilement les direct offer nombres et direct routing .

Les direct offer nombres sont de deux types : Géographique et Gratuit. Les forfaits téléphoniques géographiques sont des forfaits téléphoniques associés à un emplacement, dont les indicatifs régionaux des numéros de téléphone sont associés à l’indicatif régional d’un emplacement géographique. Toll-Free forfaits téléphoniques sont des forfaits téléphoniques qui ne sont pas associés à l’emplacement. Par exemple, aux États-Unis, les numéros gratuits peuvent être fournis avec des indicatifs régionaux tels que 800 ou 888. Ils sont gérés à l’aide du PhoneNumbersClient

La direct routing fonctionnalité permet de connecter votre infrastructure de téléphonie existante à ACS. La configuration est gérée à l’aide de SipRoutingClient, qui fournit des méthodes pour configurer des jonctions SIP et des règles de routage vocal, afin de gérer correctement les appels pour votre sous-réseau de téléphonie.

Initialisation du client

Les clients peuvent être initialisés à l’aide de l’authentification 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();

L’utilisation du point de terminaison et de la clé d’accès à partir de la ressource de communication pour l’authentification est également possible.

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

Vous pouvez également fournir l’intégralité du chaîne de connexion à l’aide de la fonction connectionString() du client au lieu de fournir le point de terminaison et la clé d’accès.

Client numéros de téléphone

Vue d’ensemble des types de numéros de téléphone

Les numéros de téléphone sont de deux types : Géographique et gratuit. Les forfaits téléphoniques géographiques sont des forfaits téléphoniques associés à un emplacement, dont les indicatifs régionaux des numéros de téléphone sont associés à l’indicatif régional d’un emplacement géographique. Toll-Free forfaits téléphoniques sont des forfaits téléphoniques qui ne sont pas associés à l’emplacement. Par exemple, aux États-Unis, les numéros gratuits peuvent être fournis avec des indicatifs régionaux tels que 800 ou 888.

Recherche et achat et publication de numéros

Les numéros de téléphone peuvent être recherchés via l’API de création de recherche en fournissant un indicatif régional, une quantité de numéros de téléphone, un type d’application, un type de numéro de téléphone et des fonctionnalités. La quantité de numéros de téléphone fournie sera réservée pendant dix minutes et peut être achetée dans ce délai. Si la recherche n’est pas achetée, les numéros de téléphone seront disponibles pour d’autres personnes au bout de dix minutes. Si la recherche est achetée, les numéros de téléphone sont achetés pour les ressources Azure.

Les numéros de téléphone peuvent également être publiés à l’aide de l’API de mise en production.

Client de routage SIP

La fonctionnalité de routage direct permet de connecter l’infrastructure de téléphonie fournie par le client à Azure Communication Resources. Pour configurer correctement la configuration du routage, le client doit fournir la configuration de jonction SIP et les règles de routage SIP pour les appels. Le client de routage SIP fournit l’interface nécessaire pour définir cette configuration.

Lorsque l’appel arrive, le système tente de faire correspondre le numéro de destination avec les modèles de numéros regex des itinéraires définis. Le premier itinéraire correspondant au numéro est sélectionné. L’ordre de correspondance regex est le même que celui des itinéraires dans la configuration, donc l’ordre des itinéraires est important. Une fois qu’un itinéraire est mis en correspondance, l’appel est acheminé vers la première jonction de la liste des jonctions de l’itinéraire. Si la jonction n’est pas disponible, la jonction suivante dans la liste est sélectionnée.

Exemples

PhoneNumbersClient

Obtenir le numéro de téléphone acheté

Obtient le numéro de téléphone acheté spécifié.

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

Obtenir tous les numéros de téléphone achetés

Répertorie tous les numéros de téléphone achetés.

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

Opérations de longue durée

Le client numéro de téléphone prend en charge diverses opérations de longue durée qui autorisent un temps d’interrogation indéfini pour les fonctions répertoriées ci-dessous.

Rechercher les numéros de téléphone disponibles

Recherchez les numéros de téléphone disponibles en fournissant l’indicatif régional, le type d’affectation, les fonctionnalités de numéro de téléphone, le type de numéro de téléphone et la quantité. Le résultat de la recherche peut ensuite être utilisé pour acheter les nombres. Notez que pour le type de numéro de téléphone gratuit, l’indicatif régional est facultatif.

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

Acheter des numéros de téléphone

Le résultat de la recherche de numéros de téléphone correspond à PhoneNumberSearchResult. Vous pouvez l’utiliser pour obtenir les détails des numéros et les numéros d’achat en transmettant à l’API searchId du numéro d’achat.

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

Libérer un numéro de téléphone

Libère un numéro de téléphone acheté.

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

Mise à jour des fonctionnalités de numéro de téléphone

Mises à jour fonctionnalités de numéro de téléphone pour les appels et les SMS à l’un des éléments suivants :

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

Récupérer des jonctions et des itinéraires SIP

Obtenez la liste des jonctions ou des itinéraires actuellement configurés.

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

Remplacer des jonctions et des itinéraires SIP

Remplacez la liste des jonctions ou itinéraires actuellement configurés par de nouvelles valeurs.

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

Récupérer une jonction unique

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

Définir une jonction unique

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

Supprimer une jonction unique

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

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Dépannage

En cours.

Étapes suivantes

Consulter d’autres bibliothèques clientes pour le service de communication Azure

Impressions

Partager via