適用于 Python 的 Azure 通訊電話號碼套件用戶端程式庫 - 1.1.0 版

發行項
03/30/2023

Azure 通訊電話號碼用戶端套件是用來管理電話號碼。

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691

開始使用

Prerequisites

需要 Python 3.7 或更新版本才能使用此套件。
您必須擁有 Azure 訂用帳戶
已部署通訊服務資源。您可以使用Azure 入口網站或 Azure PowerShell來設定。

安裝套件

使用 pip安裝適用于 Python 的 Azure 通訊電話號碼用戶端程式庫：

pip install azure-communication-phonenumbers

重要概念

此 SDK 提供輕鬆管理和 direct offerdirect routing 數位的功能。

數位 direct offer 有兩種類型：地理和免付費。地理電話方案是與某個位置相關聯的電話方案，其電話號碼的區功能變數代碼會與地理位置的區功能變數代碼相關聯。 Toll-Free電話方案是沒有關聯位置的電話方案。例如，在美國，免付費電話號碼可以隨附區功能變數代碼，例如 800 或 888。它們是使用管理 PhoneNumbersClient

此功能 direct routing 可讓您將現有的電話語音基礎結構連線到 ACS。組態是使用 SipRoutingClient 管理，其提供設定 SIP 主幹和語音路由規則的方法，以便正確處理電話語音子網的通話。

初始化用戶端

用戶端可以使用 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())

另一個選項是使用資源的連接字串來初始化用戶端。

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

電話號碼用戶端

電話號碼類型概觀

電話號碼有兩種類型：地理和免付費。地理電話號碼是與位置相關聯的電話號碼，其區功能變數代碼與地理位置的區功能變數代碼相關聯。 Toll-Free電話號碼是沒有相關聯位置的電話號碼。例如，在美國，免付費電話號碼可以隨附區功能變數代碼，例如 800 或 888。

搜尋和購買和釋放數位

您可以透過搜尋建立 API 來搜尋電話號碼，方法是提供區功能變數代碼、電話號碼數量、應用程式類型、電話號碼類型和功能。提供的電話號碼數量將會保留 10 分鐘，而且可以在這段時間內購買。如果未購買搜尋，電話號碼將在十分鐘後可供其他人使用。如果已購買搜尋，則會取得 Azure 資源的電話號碼。

您也可以使用發行 API 來釋出電話號碼。

SIP 路由用戶端

直接路由功能可讓您將客戶提供的電話語音基礎結構連線到 Azure 通訊資源。若要正確設定路由設定，客戶必須提供 SIP 主幹組態和 SIP 路由規則以進行通話。 SIP 路由用戶端提供設定此設定的必要介面。

進行呼叫時，系統會嘗試比對目的地號碼與已定義路由的 RegEx 號碼模式。將會選取符合數位的第一個路由。 RegEx 比對的順序與組態中的路由順序相同，因此路由的順序很重要。比對路由之後，呼叫會路由傳送至路由主幹清單中的第一個主幹。如果主幹無法使用，則會選取清單中的下一個主幹。

範例

PhoneNumbersClient

取得所有購買的電話號碼

列出您所有購買的電話號碼

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

取得購買的電話號碼

從指定的電話號碼取得資訊

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

長時間執行的作業

電話號碼用戶端支援各種長時間執行的作業，允許無限期輪詢下列函式。

搜尋可用的電話號碼

您可以藉由提供您想要取得的電話功能、電話號碼類型、指派類型和國家/地區代碼，來搜尋可用的電話號碼。值得一提的是，對於免付費電話號碼類型，證明區功能變數代碼是選擇性的。搜尋的結果接著可用來購買對應 API 中的號碼。

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

購買電話號碼

搜尋的結果可用來購買指定的電話號碼。這可以透過從搜尋回應傳遞 search_id 至購買電話號碼 API 來完成。

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

發行電話號碼

釋放取得的電話號碼。

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

更新電話號碼功能

更新通話和簡訊的指定電話號碼功能設為下列其中一項：

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

擷取 SIP 主幹和路由

取得目前設定主幹或路由的清單。

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)

取代 SIP 主幹和路由

以新的值取代目前設定主幹或路由的清單。

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)

擷取單一主

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

設定單一主幹

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

刪除單一主幹

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

疑難排解

電話號碼管理用戶端將會引發 Azure Core中定義的例外狀況。

下一步

提供意見反應

如果您遇到任何錯誤或有建議，請在專案的 [問題 ] 區段中提出問題

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

共用方式為