Azure Communication Phone Numbers Package-Clientbibliothek für Python – Version 1.1.0

Artikel
03/30/2023

Das Clientpaket "Azure Communication Phone Numbers" wird zum Verwalten von Telefonnummern verwendet.

Haftungsausschluss

Die Unterstützung von Azure SDK-Python-Paketen für Python 2.7 endet am 01. Januar 2022. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

Für die Verwendung dieses Pakets ist Python 3.7 oder höher erforderlich.
Sie benötigen ein Azure-Abonnement.
Eine bereitgestellte Communication Services-Ressource. Sie können das Azure-Portal oder die Azure PowerShell zum Einrichten verwenden.

Installieren des Pakets

Installieren Sie die Clientbibliothek für Azure Communication Phone Numbers für Python mit pip:

pip install azure-communication-phonenumbers

Wichtige Begriffe

Dieses SDK bietet Funktionen zum einfachen Verwalten direct offer von Und direct routing Zahlen.

Die direct offer Zahlen sind in zwei Arten verfügbar: geografisch und gebührenfrei. Geografische Telefonpläne sind Telefonpläne, die einem Standort zugeordnet sind, dessen Telefonnummern mit der Ortsvorwahl eines geografischen Standorts verknüpft sind. Toll-Free Telefontarife sind Telefonpläne, die nicht dem Standort zugeordnet sind. In den USA können beispielsweise gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 enthalten sein. Sie werden mithilfe der PhoneNumbersClient

Das direct routing Feature ermöglicht das Verbinden Ihrer vorhandenen Telefonieinfrastruktur mit ACS. Die Konfiguration wird mithilfe von SipRoutingClientverwaltet, das Methoden zum Einrichten von SIP-Trunks und VoIP-Routingregeln bereitstellt, um Anrufe für Ihr Telefonsubnetz ordnungsgemäß zu verarbeiten.

Initialisieren des Clients

Der Client kann mithilfe der AAD-Authentifizierung initialisiert werden.

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

Eine weitere Möglichkeit besteht darin, den Client mithilfe der Verbindungszeichenfolge der Ressource zu initialisieren.

# 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)

Telefonnummern-Client

Übersicht über Telefonnummerntypen

Telefonnummern gibt es in zwei Arten; Geografisch und gebührenfrei. Geografische Telefonnummern sind Telefonnummern, die einem Standort zugeordnet sind, dessen Ortsvorwahlen der Ortsvorwahl eines geografischen Standorts zugeordnet sind. Toll-Free Telefonnummern sind Telefonnummern ohne zugeordneten Standort. In den USA können beispielsweise gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 enthalten sein.

Suchen und Kaufen und Freigeben von Nummern

Telefonnummern können über die Sucherstellungs-API durchsucht werden, indem eine Ortsvorwahl, anzahl von Telefonnummern, Anwendungstyp, Telefonnummerntyp und Funktionen angegeben werden. Die angegebene Anzahl von Telefonnummern wird für zehn Minuten reserviert und kann innerhalb dieser Zeit erworben werden. Wenn die Suche nicht gekauft wird, werden die Telefonnummern nach zehn Minuten für andere Personen verfügbar. Wenn die Suche erworben wird, werden die Telefonnummern für die Azure-Ressourcen abgerufen.

Telefonnummern können auch mithilfe der Release-API veröffentlicht werden.

SIP-Routingclient

Das Feature "Direct Routing" ermöglicht das Verbinden der vom Kunden bereitgestellten Telefonieinfrastruktur mit Azure Communication Resources. Um die Routingkonfiguration ordnungsgemäß einzurichten, muss der Kunde die SIP-Trunkkonfiguration und SIP-Routingregeln für Anrufe angeben. Der SIP-Routingclient stellt die erforderliche Schnittstelle zum Festlegen dieser Konfiguration bereit.

Wenn ein Aufruf erfolgt, versucht das System, die Zielnummer mit regex-Nummernmustern definierter Routen abzugleichen. Die erste Route, die mit der Nummer übereinstimmt, wird ausgewählt. Die Reihenfolge des RegEx-Abgleichs ist identisch mit der Reihenfolge der Routen in der Konfiguration, daher ist die Reihenfolge der Routen wichtig. Sobald eine Route abgeglichen wurde, wird der Anruf an den ersten Trunk in der Trunkliste der Route weitergeleitet. Wenn der Trunk nicht verfügbar ist, wird der nächste Trunk in der Liste ausgewählt.

Beispiele

PhoneNumbersClient

Abrufen aller erworbenen Telefonnummern

Listet alle erworbenen Telefonnummern auf.

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

Erworbene Telefonnummer abrufen

Ruft die Informationen von der angegebenen Telefonnummer ab.

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

Vorgänge mit langer Ausführungsdauer

Der Telefonnummernclient unterstützt eine Vielzahl von Vorgängen mit langer Ausführungszeit, die eine unbegrenzte Abrufzeit für die unten aufgeführten Funktionen ermöglichen.

Suchen Nach verfügbarer Telefonnummer

Sie können nach verfügbaren Telefonnummern suchen, indem Sie die Funktionen des gewünschten Telefons, den Telefonnummerntyp, den Zuweisungstyp und die Landesvorwahl angeben. Es ist erwähnenswert, dass für den gebührenfreien Telefonnummerntyp, der nachweist, dass die Vorwahl optional ist. Das Ergebnis der Suche kann dann verwendet werden, um die Nummer in der entsprechenden API zu erwerben.

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

Kaufen von Telefonnummern

Das Ergebnis Ihrer Suche kann verwendet werden, um die angegebenen Telefonnummern zu erwerben. Dies kann durch Übergeben von search_id aus der Suchantwort an die API für die Kauftelefonnummer erfolgen.

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

Freigeben einer Telefonnummer

Gibt eine erworbene Telefonnummer frei.

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

Aktualisieren von Telefonnummernfunktionen

Aktualisierungen die angegebenen Telefonnummernfunktionen für Anrufe und SMS an eine der folgenden Funktionen:

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

Abrufen von SIP-Trunks und -Routen

Rufen Sie die Liste der derzeit konfigurierten Trunks oder Routen ab.

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)

Ersetzen von SIP-Trunks und -Routen

Ersetzen Sie die Liste der aktuell konfigurierten Trunks oder Routen durch neue Werte.

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)

Abrufen eines einzelnen Trunks

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

Festlegen eines einzelnen Trunks

# 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)

Löschen eines einzelnen Trunks

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

Problembehandlung

Der Client für die Telefonnummernverwaltung löst ausnahmen aus, die in Azure Core definiert sind.

Nächste Schritte

Weiterer Beispielcode

Ausführliche Beispiele für die Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis .

Feedback geben

Wenn Fehler auftreten oder Vorschläge vorliegen, melden Sie ein Problem im Abschnitt Probleme des Projekts.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Share via