適用于 .NET 的 Azure 通訊電話號碼用戶端程式庫 - 1.1.0 版

發行項
04/03/2023

Azure 通訊電話號碼正在管理Azure 通訊服務的電話號碼。

開始使用

安裝套件

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

dotnet add package Azure.Communication.PhoneNumbers

必要條件

您需要 Azure 訂用帳戶和通訊服務資源，才能使用此套件。

若要建立新的通訊服務，您可以使用Azure 入口網站、Azure PowerShell或.NET 管理用戶端程式庫。

重要概念

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

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

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

驗證用戶端

用戶端可以使用從 Azure入口網站中的 Azure 通訊資源取得的連接字串進行驗證。

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);

// Get a connection string to Azure Communication resource.
var connectionString = "<connection_string>";
var client = new SipRoutingClient(connectionString);

用戶端也可以選擇使用 Azure Active Directory 驗證進行驗證。如需本主題的詳細資訊，請參閱 Azure 身分識別。

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new SipRoutingClient(endpoint, tokenCredential);

電話號碼用戶端

電話號碼類型概觀

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

相同國家/地區中的所有地理電話方案都會分組為具有地理電話號碼類型的電話方案群組。相同國家/地區內的所有Toll-Free電話方案都會分組為電話方案群組。

搜尋、購買和釋出電話號碼

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

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

SIP 路由用戶端

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

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

執行緒安全

我們保證所有用戶端實例方法都是安全線程，且彼此獨立 (指導方針) 。這可確保重複使用用戶端實例的建議一律是安全的，即使是跨執行緒也一樣。

其他概念

範例

PhoneNumbersClient

建立 PhoneNumbersClient

若要建立新的 PhoneNumbersClient ，您需要Azure 通訊服務資源的連接字串，一旦您建立資源，即可從 Azure 入口網站取得。

您可以根據環境變數、組態設定或任何適用于應用程式的方式進行設定 connectionString 。

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);

搜尋電話號碼

必須先搜尋電話號碼，才能購買電話號碼。搜尋是長時間執行的作業，可由傳回 SearchAvailablePhoneNumbersOperation 物件的函式啟動 StartSearchAvailablePhoneNumbers 。 SearchAvailablePhoneNumbersOperation 可用來更新作業的狀態，以及檢查完整性。

var capabilities = new PhoneNumberCapabilities(calling: PhoneNumberCapabilityType.None, sms: PhoneNumberCapabilityType.Outbound);

var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync(countryCode, PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities);
await searchOperation.WaitForCompletionAsync();

購買電話號碼

您可以透過購買搜尋來取得電話號碼。

var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();

列出購買的電話號碼

您可以列出已為您的資源購買的所有電話號碼。

var purchasedPhoneNumbers = client.GetPurchasedPhoneNumbersAsync();

await foreach (var phoneNumber in purchasedPhoneNumbers)
{
    Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}, monthly cost: {phoneNumber.Cost}");
}

釋放電話號碼

如果您不再需要電話號碼，可以釋出電話號碼。

var purchasedPhoneNumber = "<purchased_phone_number>";
var releaseOperation = await client.StartReleasePhoneNumberAsync(purchasedPhoneNumber);
await releaseOperation.WaitForCompletionResponseAsync();
await WaitForCompletionResponseAsync(releaseOperation);

SipRoutingClient

擷取 SIP 主幹和路由

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

var trunksResponse = await client.GetTrunksAsync();
var routesResponse = await client.GetRoutesAsync();

取代 SIP 主幹和路由

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

// The service will not allow trunks that are used in any of the routes to be deleted, therefore first set the routes as empty list, and then update the routes.
var newTrunks = "<new_trunks_list>";
var newRoutes = "<new_routes_list>";
await client.SetRoutesAsync(new List<SipTrunkRoute>());
await client.SetTrunksAsync(newTrunks);
await client.SetRoutesAsync(newRoutes);

管理單一主幹

SIP 主幹可以使用來擷取、設定或刪除單一主幹，個別 SipRoutingClient 管理 SIP 主幹。

擷取單一主

// Get trunk object, based on it's FQDN.
var fqdnToRetrieve = "<fqdn>";
var trunkResponse = await client.GetTrunkAsync(fqdnToRetrieve);

設定單一主幹

// Set function will either modify existing item or add new item to the collection.
// The trunk is matched based on it's FQDN.
var trunkToSet = "<trunk_to_set>";
await client.SetTrunkAsync(trunkToSet);

刪除單一主幹

// Deletes trunk with supplied FQDN.
var fqdnToDelete = "<fqdn>";
await client.DeleteTrunkAsync(fqdnToDelete);

疑難排解

後續步驟

深入瞭解如何管理電話號碼

深入瞭解直接路由

參與

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

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

共用方式為