Bibliothèque cliente du package Numéros de téléphone Azure Communication pour Python - version 1.1.0

Article
03/30/2023

Le package client Numéros de téléphone Azure Communication est utilisé pour administrer les numéros de téléphone.

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Prérequis

Python 3.7 ou version ultérieure est requis pour utiliser ce package.
Vous devez disposer d’un abonnement Azure
Une ressource Communication Services déployée. Vous pouvez utiliser le portail Azure ou le Azure PowerShell pour le configurer.

Installer le package

Installez la bibliothèque cliente Azure Communication Phone Numbers pour Python avec pip :

pip install azure-communication-phonenumbers

Concepts clés

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

Les direct offer nombres sont de deux types : Géographique et Gratuit. Les forfaits de téléphonie géographique sont des forfaits de téléphone associés à un emplacement, dont les codes 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 de configuration 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

Le client peut être initialisé à l’aide de l’authentification AAD.

import os
from azure.communication.phonenumbers import PhoneNumbersClient
from azure.identity import DefaultAzureCredential

endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
phone_numbers_client = PhoneNumbersClient(endpoint, DefaultAzureCredential())

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient
from azure.identity import DefaultAzureCredential

endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
sip_routing_client = SipRoutingClient(endpoint, DefaultAzureCredential())

Une autre option consiste à initialiser le client à l’aide de la chaîne de connexion de la ressource.

# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers import PhoneNumbersClient

connection_str = "endpoint=ENDPOINT;accessKey=KEY"
phone_numbers_client = PhoneNumbersClient.from_connection_string(connection_str)

# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient

connection_str = "endpoint=ENDPOINT;accessKey=KEY"
sip_routing_client = SipRoutingClient.from_connection_string(connection_str)

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 numéros de téléphone géographiques sont des numéros de téléphone associés à un emplacement, dont les indicatifs régionaux sont associés à l’indicatif régional d’un emplacement géographique. Toll-Free numéros de téléphone sont des numéros de téléphone sans emplacement associé. 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 libération 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 accessibles aux autres au bout de dix minutes. Si la recherche est achetée, les numéros de téléphone sont acquis 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.

Lorsqu’un appel est effectué, 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. La première route correspondant au nombre sera sélectionnée. L’ordre de correspondance regex est le même que l’ordre des itinéraires dans la configuration. Par conséquent, l’ordre des itinéraires est important. Une fois qu’un itinéraire est mis en correspondance, l’appel est acheminé vers le premier tronc 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 tous les numéros de téléphone achetés

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

purchased_phone_numbers = phone_numbers_client.list_purchased_phone_numbers()
for acquired_phone_number in purchased_phone_numbers:
    print(acquired_phone_number.phone_number)

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

Obtient les informations du numéro de téléphone spécifié

result = phone_numbers_client.get_purchased_phone_number("<phone number>")
print(result.country_code)
print(result.phone_number)

Opérations à long terme

Le client numéro de téléphone prend en charge une variété d’opérations de longue durée qui permettent une durée d’interrogation indéfinie sur les fonctions répertoriées ci-dessous.

Rechercher le numéro de téléphone disponible

Vous pouvez rechercher les numéros de téléphone disponibles en fournissant les fonctionnalités du téléphone que vous souhaitez acquérir, le type de numéro de téléphone, le type d’affectation et l’indicatif de pays. Il est utile de mentionner que pour le type de numéro de téléphone gratuit, la preuve de l’indicatif régional est facultative. Le résultat de la recherche peut ensuite être utilisé pour acheter le numéro dans l’API correspondante.

capabilities = PhoneNumberCapabilities(
        calling = PhoneNumberCapabilityType.INBOUND,
        sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
    )
poller = phone_numbers_client.begin_search_available_phone_numbers(
    "US",
    PhoneNumberType.TOLL_FREE,
    PhoneNumberAssignmentType.APPLICATION,
    capabilities,
    area_code ="833", # Area code is optional for toll-free numbers
    quantity = 2, # Quantity is optional. If not set, default is 1
    polling = True
)
search_result = poller.result()

Acheter des numéros de téléphone

Le résultat de votre recherche peut être utilisé pour acheter les numéros de téléphone spécifiés. Pour ce faire, passez le search_id de la réponse de recherche à l’API du numéro de téléphone d’achat.

purchase_poller = phone_numbers_client.begin_purchase_phone_numbers(
    search_result.search_id,
    polling=True
)

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

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

poller = self.phone_number_client.begin_release_phone_number(
    "<phone number>",
    polling = True
)

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

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

PhoneNumberCapabilityType.NONE
PhoneNumberCapabilityType.INBOUND
PhoneNumberCapabilityType.OUTBOUND
PhoneNumberCapabilityType.INBOUND_OUTBOUND

poller = self.phone_number_client.begin_update_phone_number_capabilities(
    "<phone number>",
    PhoneNumberCapabilityType.OUTBOUND,
    PhoneNumberCapabilityType.INBOUND_OUTBOUND,
    polling = True
)

SipRoutingClient

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

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

trunks = sip_routing_client.list_trunks()
for trunk in trunks:
    print(trunk.fqdn)
    print(trunk.sip_signaling_port)
routes = sip_routing_client.list_routes()
for route in routes:
    print(route.name)
    print(route.description)
    print(route.number_pattern)
    for trunk_fqdn in route.trunks:
        print(trunk_fqdn)

Remplacer les jonctions et les itinéraires SIP

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

new_trunks = [SipTrunk(fqdn="sbs1.contoso.com", sip_signaling_port=1122), SipTrunk(fqdn="sbs2.contoso.com", sip_signaling_port=1123)]
new_routes = [SipTrunkRoute(name="First rule", description="Handle numbers starting with '+123'", number_pattern="\+123[0-9]+", trunks=["sbs1.sipconfigtest.com"])]
sip_routing_client.set_trunks(new_trunks)
sip_routing_client.set_routes(new_routes)

Récupérer une jonction unique

trunk = sip_routing_client.get_trunk("sbs1.contoso.com")

Définir une jonction unique

# Set function will either modify existing item or add new item to the collection.
# The trunk is matched based on it's FQDN.
new_trunk = SipTrunk(fqdn="sbs3.contoso.com", sip_signaling_port=5555)
sip_routing_client.set_trunk(new_trunk)

Supprimer une jonction unique

sip_routing_client.delete_trunk("sbs1.contoso.com")

Dépannage

Le client Administration des numéros de téléphone déclenche des exceptions définies dans Azure Core.

Étapes suivantes

Autres exemples de code

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Fournir des commentaires

Si vous rencontrez des bogues ou si vous avez des suggestions, veuillez déposer un problème dans la section Problèmes du projet

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

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.

Partager via