共用方式為


快速入門:以程式設計方式設定語音路由

設定 Azure 通訊服務直接路由的傳出語音路由規則。

必要條件

注意

您可以在 GitHub 上找到更多SipRoutingClient 的使用範例。

新增工作階段邊界控制器

  1. 在左窗格的 [語音通話 - PSTN] 下,選取 [直接路由]。 在 [工作階段邊界控制器] 索引標籤上,選取 [設定]

  2. 輸入 SBC 的 FQDN 和訊號連接埠。 SBC FQDN 的需求包括:

    • 必須先驗證 FQDN 的網域部分,才能將它新增至直接路由設定,如之前在必要條件中所述。
    • SBC 憑證必須符合名稱。 支援萬用字元憑證。
    • 您不能使用 *.onmicrosoft.com*.azure.com 網域作為 FQDN。

    如需完整的需求清單,請參閱 Azure 直接路由基礎結構需求

    Screenshot of adding a session border controller on the panel for configuring direct routing.

  3. 選取 [下一步]。 如果一切都已正確設定,您應該會在 Azure 入口網站中看到 SBC 的狀態為作用中

    Screenshot of SBC connection properties.

重要

在撥打或接聽電話之前,請確定 SBC 狀態為在線

建立語音路由規則

Screenshot of outgoing voice routing configuration.

為您的語音路由指定名稱、使用規則運算式指定號碼模式,然後選取該模式的 SBC。 以下是基本規則運算式的一些範例:

  • ^\+\d+$:符合具有開頭為加號的一或多個數字的電話號碼。
  • ^\+1(\d{10})$:符合 +1 後面有十位數的電話號碼。
  • ^\+1(425|206)(\d{7})$:符合開頭為 +1425+1206 且後面接著七個數字的電話號碼。
  • ^\+0?1234$:符合 +01234+1234 電話號碼。

如需有關規則運算式的詳細資訊,請參閱 .NET 規則運算式概觀

您可以針對單一模式選取多個 SBC。 在這種情況下,路由演算法會以隨機順序加以選擇。 您也可以指定一次以上的確切數字模式。 資料列越高,優先順序越高。 如果無法使用與該資料列相關聯的所有 SBC,則會選取下一個資料列。 如此一來,您會建立複雜的路由案例。

移除直接路由設定

若要刪除語音路由:

  1. 在左窗格的 [語音通話 - PSTN] 下方,前往 [直接路由]
  2. 在 [語音路由] 索引標籤上,選取您要刪除的一或多個路由所適用的核取方塊。
  3. 選取 [移除]。

若要刪除 SBC:

  1. 在左窗格的 [語音通話 - PSTN] 下方,前往 [直接路由]
  2. 在 [工作階段邊界控制器] 索引標籤上,選取 [設定]
  3. 清除您要移除的 SBC 所適用的 FQDN 和連接埠欄位,然後選取 [下一步]
  4. 在 [語音路由] 索引標籤上,檢閱語音路由設定。 視需要進行變更,然後選取 [儲存]

當您移除與語音路由相關聯的 SBC 時,您可以在 [語音路由] 索引標籤上為該路由選擇不同的 SBC。系統會刪除不含 SBC 的語音路由。

必要條件

最終程式碼

GitHub 上找到此快速入門的完成程式碼。

您也可以在 GitHub 上找到更多 SipRoutingClient 的使用範例。

建立 C# 應用程式

在主控台視窗中 (例如命令提示字元、PowerShell 或 Bash),使用 dotnet new 命令建立新的主控台應用程式:

    dotnet new console -o DirectRoutingQuickstart

此命令會建立簡單的 "Hello World" C# 專案,內含單一原始程式檔:Program.cs

將您的目錄變更為新建立的應用程式資料夾,然後使用 dotnet build 命令來編譯您的應用程式:

    cd DirectRoutingQuickstart
    dotnet build

Install the package

若您仍在應用程式目錄中,請使用 dotnet add package 命令安裝適用於 .NET 的 Azure Communication PhoneNumbers 用戶端程式庫:

    dotnet add package Azure.Communication.PhoneNumbers --version 1.1.0

using 指示詞新增至 Program.cs 的頂端,以包含命名空間:

using Azure.Communication.PhoneNumbers.SipRouting;

驗證用戶端

使用來自 Azure 通訊服務資源的連接字串來驗證電話號碼用戶端:

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

設定直接路由設定

必要條件中,您已驗證網域所有權。 後續步驟是建立主幹 (新增 SBC),並建立語音路由。

建立或更新主幹

Azure 通訊服務直接路由只允許與已註冊的 SBC 通訊。 若要註冊 SBC,您需要其 FQDN 和連接埠:

// Register your SBCs by providing their fully qualified domain names and port numbers.
var usSbcFqdn = "sbc.us.contoso.com";
var euSbcFqdn = "sbc.eu.contoso.com";
var sbcPort = 5061;

var usTrunk = new SipTrunk(usSbcFqdn, sbcPort);
var euTrunk = new SipTrunk(euSbcFqdn, sbcPort);

await client.SetTrunksAsync(new List<SipTrunk> { usTrunk, euTrunk });

建立或更新路由

提供外撥通話的路由規則。 每個規則都包含兩個部分:應該符合撥號電話號碼的 RegEx 模式,以及路由傳送通話所在位置的已註冊主幹 FQDN。

路由順序決定路由的優先順序。 系統挑選第一個符合 RegEx 的路由進行通話。

在此範例中,您會為開頭為 +1 的數字建立一個路由,並為開頭只有 + 的數字建立第二個路由:

var usRoute = new SipTrunkRoute("UsRoute", "^\\+1(\\d{10})$", trunks: new List<string> { usSbcFqdn });
var defaultRoute = new SipTrunkRoute("DefaultRoute", "^\\+\\d+$", trunks: new List<string> { usSbcFqdn, euSbcFqdn });

await client.SetRoutesAsync(new List<SipTrunkRoute> { usRoute, defaultRoute });

更新直接路由設定

您可以使用相同的 FQDN 覆寫記錄,以更新特定主幹的屬性。 例如,您可以設定新的 SBC 連接埠值:

var usTrunk = new SipTrunk("sbc.us.contoso.com", 5063);
await client.SetTrunkAsync(usTrunk);

您可以使用相同的方法來建立和更新路由規則。 當您更新路由時,請在單一更新中傳送所有路由。 新的路由設定會完整覆寫先前的路由設定。

移除直接路由設定

您無法編輯或移除單一語音路由。 您應該覆寫整個語音路由設定。 以下是移除所有路由和主幹的空白清單範例:

//delete all configured voice routes
await client.SetRoutesAsync(new List<SipTrunkRoute>());

//delete all trunks
await client.SetTrunksAsync(new List<SipTrunk>());

您可以使用下列範例來刪除單一主幹 (SBC),如果沒有任何語音路由正在使用該主幹的話。 如果 SBC 列在任何語音路由中,請先刪除該路由。

await client.DeleteTrunkAsync("sbc.us.contoso.com");

必要條件

最終程式碼

GitHub 上找到此快速入門的完成程式碼。

您也可以在 GitHub 上找到更多 SipRoutingClient 的使用範例。

建立 Java 應用程式

開啟您的終端機或命令視窗。 前往您要在其中建立 Java 應用程式的目錄。 然後,執行命令以從 maven-archetype-quickstart 範本產生 Java 專案:

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

generate 工作會建立名稱與 artifactId 值相同的目錄。 在此目錄下,src/main/java 目錄包含專案原始程式碼,src/test/java 目錄包含測試來源,而 pom.xml 檔案是專案的「專案物件模型」(POM)。

Install the package

在文字編輯器中開啟 pom.xml 檔案。 將下列相依性元素新增至相依性群組:

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

設定應用程式架構

從專案目錄:

  1. 移至 /src/main/java/com/communication/quickstart 目錄。
  2. 在編輯器中開啟 App.java 檔案。
  3. 取代 System.out.println("Hello world!"); 陳述式。
  4. 新增 import 指示詞。

使用下列程式碼開始作業:

import com.azure.communication.phonenumbers.siprouting.SipRoutingAsyncClient;
import com.azure.communication.phonenumbers.siprouting.SipRoutingClientBuilder;
import com.azure.communication.phonenumbers.siprouting.models.SipTrunk;
import com.azure.communication.phonenumbers.siprouting.models.SipTrunkRoute;
import static java.util.Arrays.asList;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Direct Routing Quickstart");
        // Quickstart code goes here
    }
}

驗證用戶端

透過 SipRoutingClientBuilder,您可以使用 Microsoft Entra 驗證:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

SipRoutingAsyncClient sipRoutingAsyncClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

或者,您也可以使用來自通訊資源的端點和存取金鑰進行驗證:

// You can find your connection string from your resource in the Azure portal
String connectionString = "endpoint=https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<ACCESS_KEY>";

SipRoutingAsyncClient sipRoutingAsyncClient = new SipRoutingClientBuilder()
    .connectionString(connectionString)
    .buildClient();

設定直接路由設定

必要條件中,您已驗證網域所有權。 後續步驟是建立主幹 (新增 SBC),並建立語音路由。

建立或更新主幹

Azure 通訊服務直接路由只允許與已註冊的 SBC 通訊。 若要註冊 SBC,您需要其 FQDN 和連接埠:

sipRoutingAsyncClient.setTrunksWithResponse(asList(
	new SipTrunk("sbc.us.contoso.com", 5061),
	new SipTrunk("sbc.eu.contoso.com", 5061)
)).block();

建立或更新路由

提供外撥通話的路由規則。 每個規則都包含兩個部分:應該符合撥號電話號碼的 RegEx 模式,以及路由傳送通話所在位置的已註冊主幹 FQDN。

路由順序決定路由的優先順序。 系統挑選第一個符合 RegEx 的路由進行通話。

在此範例中,您會為開頭為 +1 的數字建立一個路由,並為開頭只有 + 的數字建立第二個路由:

sipRoutingAsyncClient.setRoutes(asList(
	new SipTrunkRoute("UsRoute", "^\\+1(\\d{10})$").setTrunks(asList("sbc.us.contoso.com")),
	new SipTrunkRoute("DefaultRoute", "^\\+\\d+$").setTrunks(asList("sbc.us.contoso.com", "sbc.eu.contoso.com"))
)).block();

更新直接路由設定

您可以使用相同的 FQDN 覆寫記錄,以更新特定主幹的屬性。 例如,您可以設定新的 SBC 連接埠值:

sipRoutingClient.setTrunk(new SipTrunk("sbc.us.contoso.com", 5063));

您可以使用相同的方法來建立和更新路由規則。 當您更新路由時,請在單一更新中傳送所有路由。 新的路由設定會完整覆寫先前的路由設定。

移除直接路由設定

您無法編輯或移除單一語音路由。 您應該覆寫整個語音路由設定。 以下是移除所有路由和主幹的空白清單範例。

新增兩個匯入:

import java.util.Collections;
import java.util.List;

使用下列程式碼來刪除直接路由設定:

//delete all configured voice routes
System.out.println("Delete all routes");
List<SipTrunkRoute> routes = Collections.<SipTrunkRoute> emptyList();
sipRoutingAsyncClient.setRoutes(routes).block();

//delete all trunks
System.out.println("Delete all trunks");
List<SipTrunk> trunks = Collections.<SipTrunk> emptyList();
sipRoutingAsyncClient.setTrunksWithResponse(trunks).block();

您可以使用下列範例來刪除單一主幹 (SBC),如果沒有任何語音路由正在使用該主幹的話。 如果 SBC 列在任何語音路由中,請先刪除該路由。

sipRoutingClient.deleteTrunk("sbc.us.contoso.com");

執行程式碼

移至包含 pom.xml 檔案的目錄,然後使用下列 mvn 命令來編譯專案:

  mvn clean compile

接著,建置套件:

  mvn package

執行下列 mvn 命令來執行應用程式:

  mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

必要條件

最終程式碼

GitHub 上找到此快速入門的完成程式碼。

您也可以在 GitHub 上找到更多 SipRoutingClient 的使用範例。

建立 Node.js 應用程式

開啟您的終端機或命令視窗,為您的應用程式建立新的目錄,並前往該目錄:

    mkdir direct-routing-quickstart && cd direct-routing-quickstart

執行 npm init -y 以使用預設設定建立 package.json 檔案:

   npm init -y

在您建立的目錄根中,建立名為 direct-routing-quickstart.js 的檔案。 將下列程式碼片段新增至其中:

async function main() {
    // quickstart code will go here
}

main();

Install the package

使用 npm install 命令來安裝適用於 JavaScript 的 Azure 通訊服務電話號碼用戶端程式庫:

   npm install @azure/communication-phone-numbers --save

--save 選項會在您的 package.json 檔案中,將程式庫新增為相依性。

驗證用戶端

從用戶端程式庫匯入 SipRoutingClient,並使用您的連接字串將其具現化。 此程式碼會從名為 COMMUNICATION_SERVICES_CONNECTION_STRING 的環境變數中,擷取資源的連接字串。 了解如何管理您資源的連接字串

將下列程式碼新增至 direct-routing-quickstart.js

const { SipRoutingClient } = require('@azure/communication-phone-numbers');

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the phone numbers client
const sipRoutingClient = new SipRoutingClient(connectionString);

設定直接路由設定

必要條件中,您已驗證網域所有權。 後續步驟是建立主幹 (新增 SBC),並建立語音路由。

建立或更新主幹

Azure 通訊服務直接路由只允許與已註冊的 SBC 通訊。 若要註冊 SBC,您需要其 FQDN 和連接埠:

  await client.setTrunks([
    {
      fqdn: 'sbc.us.contoso.com',
      sipSignalingPort: 5061
    },{
      fqdn: 'sbc.eu.contoso.com',
      sipSignalingPort: 5061
    }
  ]);

建立或更新路由

提供外撥通話的路由規則。 每個規則都包含兩個部分:應該符合撥號電話號碼的 RegEx 模式,以及路由傳送通話所在位置的已註冊主幹 FQDN。

路由順序決定路由的優先順序。 系統挑選第一個符合 RegEx 的路由進行通話。

在此範例中,您會為開頭為 +1 的數字建立一個路由,並為開頭只有 + 的數字建立第二個路由:

   await client.setRoutes([
    {
      name: "UsRoute",
      description: "route's description",
      numberPattern: "^\+1(\d{10})$",
      trunks: [ 'sbc.us.contoso.com' ]
    },{
      name: "DefaultRoute",
      description: "route's description",
      numberPattern: "^\+\d+$",
      trunks: [ 'sbc.us.contoso.com', 'sbc.eu.contoso.com']
    }
  ]);

更新直接路由設定

您可以使用相同的 FQDN 覆寫記錄,以更新特定主幹的屬性。 例如,您可以設定新的 SBC 連接埠值:

  await client.setTrunk({
    fqdn: 'sbc.us.contoso.com',
    sipSignalingPort: 5063
  });

您可以使用相同的方法來建立和更新路由規則。 當您更新路由時,請在單一更新中傳送所有路由。 新的路由設定會完整覆寫先前的路由設定。

移除直接路由設定

您無法編輯或移除單一語音路由。 您應該覆寫整個語音路由設定。 以下是移除所有路由和主幹的空白清單範例:

//delete all configured voice routes
console.log("Deleting all routes...");
await client.setRoutes([]);

//delete all trunks
console.log("Deleting all trunks...");
await client.setTrunks([]);

您可以使用下列範例來刪除單一主幹 (SBC),如果沒有任何語音路由正在使用該主幹的話。 如果 SBC 列在任何語音路由中,請先刪除該路由。

   await client.deleteTrunk('sbc.us.contoso.com');

執行程式碼

使用 node 命令來執行您新增至 direct-routing-quickstart.js 檔案的程式碼:

   node direct-routing-quickstart.js

必要條件

最終程式碼

GitHub 上找到此快速入門的完成程式碼。

您也可以在 GitHub 上找到更多 SipRoutingClient 的使用範例。

建立 Python 應用程式

開啟您的終端機或命令視窗。 為您的應用程式建立新目錄,然後前往該目錄:

mkdir direct-routing-quickstart && cd direct-routing-quickstart

使用文字編輯器在專案根目錄中建立名為 direct_routing_sample.py 的檔案,並新增下列程式碼:

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient, SipTrunk, SipTrunkRoute

try:
   print('Azure Communication Services - Direct Routing Quickstart')
   # Quickstart code goes here
except Exception as ex:
   print('Exception:')
   print(ex)

您將在下列各節中新增其餘快速入門程式碼。

Install the package

若您仍在應用程式目錄中,請使用 pip install 命令安裝適用於 Python 的 Azure 通訊服務系統管理用戶端程式庫:

pip install azure-communication-phonenumbers==1.1.0

驗證用戶端

透過 SipRoutingClient,您可以使用 Microsoft Entra 驗證。 使用 DefaultAzureCredential 物件是開始使用 Microsoft Entra ID 最簡單的方式,您可以使用 pip install 命令加以安裝:

pip install azure-identity

您必須擁有 AZURE_CLIENT_IDAZURE_CLIENT_SECRET 才能建立 DefaultAzureCredential 物件,且 AZURE_TENANT_ID 已設定為環境變數,以及已註冊 Microsoft Entra 應用程式中的對應值。 如需快速取得這些環境變數的方法,請參閱使用 Microsoft Entra ID 進行驗證

安裝 azure-identity 程式庫之後,您可以繼續驗證用戶端:

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

# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
    print('Azure Communication Services - Direct Routing Quickstart')
    credential = DefaultAzureCredential()
    sip_routing_client = SipRoutingClient(endpoint, credential)
except Exception as ex:
    print('Exception:')
    print(ex)

或者,您也可以使用來自通訊資源的端點和存取金鑰進行驗證:

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

# You can find your connection string from your resource in the Azure portal
connection_string = 'https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>'
try:
    print('Azure Communication Services - Direct Routing Quickstart')
    sip_routing_client = SipRoutingClient.from_connection_string(connection_string)
except Exception as ex:
    print('Exception:')
    print(ex)

設定直接路由設定

必要條件中,您已驗證網域所有權。 後續步驟是建立主幹 (新增 SBC),並建立語音路由。

建立或更新主幹

藉由提供其完整網域名稱和連接埠號碼來註冊 SBC:

new_trunks = [SipTrunk(fqdn="sbc.us.contoso.com", sip_signaling_port=1234), SipTrunk(fqdn="sbc.eu.contoso.com", sip_signaling_port=1234)]
sip_routing_client.set_trunks(new_trunks)

建立或更新路由

提供外撥通話的路由規則。 每個規則都包含兩個部分:應該符合撥號電話號碼的 RegEx 模式,以及路由傳送通話所在位置的已註冊主幹 FQDN。

路由順序決定路由的優先順序。 系統挑選第一個符合 RegEx 的路由進行通話。

在此範例中,您會為開頭為 +1 的數字建立一個路由,並為開頭只有 + 的數字建立第二個路由:

us_route = SipTrunkRoute(name="UsRoute", description="Handle US numbers '+1'", number_pattern="^\\+1(\\d{10})$", trunks=["sbc.us.contoso.com"])
def_route = SipTrunkRoute(name="DefaultRoute", description="Handle all numbers", number_pattern="^\\+\\d+$", trunks=["sbc.us.contoso.com","sbc.eu.contoso.com"])
new_routes = [us_route, def_route]
sip_routing_client.set_routes(new_routes)

更新直接路由設定

您可以使用相同的 FQDN 覆寫記錄,以更新特定主幹的屬性。 例如,您可以設定新的 SBC 連接埠值:

new_trunk = SipTrunk(fqdn="sbc.us.contoso.com", sip_signaling_port=5063)
sip_routing_client.set_trunk(new_trunk)

您可以使用相同的方法來建立和更新路由規則。 當您更新路由時,請在單一更新中傳送所有路由。 新的路由設定會完整覆寫先前的路由設定。

移除直接路由設定

您無法編輯或移除單一語音路由。 您應該覆寫整個語音路由設定。 以下是移除所有路由和主幹的空白清單範例:

#delete all configured voice routes
print('Deleting all routes...')
sip_routing_client.set_routes([])

#delete all trunks
print('Deleting all trunks...')
sip_routing_client.set_trunks([])

您可以使用下列範例來刪除單一主幹 (SBC),如果沒有任何語音路由正在使用該主幹的話。 如果 SBC 列在任何語音路由中,請先刪除該路由。

sip_routing_client.delete_trunk("sbc.us.contoso.com")

執行程式碼

從主控台提示,前往至包含 direct_routing_sample.py 檔案的目錄。 然後執行下列 Python 命令來執行應用程式:

python direct_routing_sample.py

清除資源

如果您想要清除並移除通訊服務訂用帳戶,您可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。 深入了解如何清除資源

下一步

如需詳細資訊,請參閱下列文章: