快速入門:以程式設計方式設定語音路由
設定 Azure 通訊服務直接路由的傳出語音路由規則。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 使用中的通訊服務資源。 建立通訊服務資源。
- 營運電話系統中工作階段邊界控制器 (SBC) 的完整網域名稱 (FQDN) 和連接埠號碼。
- SBC FQDN 經過驗證的網域名稱。
注意
您可以在 GitHub 上找到更多SipRoutingClient
的使用範例。
新增工作階段邊界控制器
在左窗格的 [語音通話 - PSTN] 下,選取 [直接路由]。 在 [工作階段邊界控制器] 索引標籤上,選取 [設定]。
輸入 SBC 的 FQDN 和訊號連接埠。 SBC FQDN 的需求包括:
- 必須先驗證 FQDN 的網域部分,才能將它新增至直接路由設定,如之前在必要條件中所述。
- SBC 憑證必須符合名稱。 支援萬用字元憑證。
- 您不能使用
*.onmicrosoft.com
和*.azure.com
網域作為 FQDN。
如需完整的需求清單,請參閱 Azure 直接路由基礎結構需求。
選取 [下一步]。 如果一切都已正確設定,您應該會在 Azure 入口網站中看到 SBC 的狀態為作用中。
重要
在撥打或接聽電話之前,請確定 SBC 狀態為在線
建立語音路由規則
為您的語音路由指定名稱、使用規則運算式指定號碼模式,然後選取該模式的 SBC。 以下是基本規則運算式的一些範例:
^\+\d+$
:符合具有開頭為加號的一或多個數字的電話號碼。^\+1(\d{10})$
:符合+1
後面有十位數的電話號碼。^\+1(425|206)(\d{7})$
:符合開頭為+1425
或+1206
且後面接著七個數字的電話號碼。^\+0?1234$
:符合+01234
和+1234
電話號碼。
如需有關規則運算式的詳細資訊,請參閱 .NET 規則運算式概觀。
您可以針對單一模式選取多個 SBC。 在這種情況下,路由演算法會以隨機順序加以選擇。 您也可以指定一次以上的確切數字模式。 資料列越高,優先順序越高。 如果無法使用與該資料列相關聯的所有 SBC,則會選取下一個資料列。 如此一來,您會建立複雜的路由案例。
移除直接路由設定
若要刪除語音路由:
- 在左窗格的 [語音通話 - PSTN] 下方,前往 [直接路由]。
- 在 [語音路由] 索引標籤上,選取您要刪除的一或多個路由所適用的核取方塊。
- 選取 [移除]。
若要刪除 SBC:
- 在左窗格的 [語音通話 - PSTN] 下方,前往 [直接路由]。
- 在 [工作階段邊界控制器] 索引標籤上,選取 [設定]。
- 清除您要移除的 SBC 所適用的 FQDN 和連接埠欄位,然後選取 [下一步]。
- 在 [語音路由] 索引標籤上,檢閱語音路由設定。 視需要進行變更,然後選取 [儲存]。
當您移除與語音路由相關聯的 SBC 時,您可以在 [語音路由] 索引標籤上為該路由選擇不同的 SBC。系統會刪除不含 SBC 的語音路由。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 作用中的 Azure 通訊服務資源和連接字串。 建立通訊服務資源。
- 適用於您作業系統的最新版本 .NET Core 用戶端程式庫。
- 營運電話系統中工作階段邊界控制器 (SBC) 的完整網域名稱 (FQDN) 和連接埠號碼。
- SBC FQDN 經過驗證的網域名稱。
最終程式碼
在 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");
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- Java 開發套件 (JDK) 第 8 版或更新版本。
- Apache Maven。
- 已部署的 Azure 通訊服務資源和連接字串。 建立通訊服務資源。
- 營運電話系統中工作階段邊界控制器 (SBC) 的完整網域名稱 (FQDN) 和連接埠號碼。
- SBC FQDN 經過驗證的網域名稱。
最終程式碼
在 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>
設定應用程式架構
從專案目錄:
- 移至 /src/main/java/com/communication/quickstart 目錄。
- 在編輯器中開啟 App.java 檔案。
- 取代
System.out.println("Hello world!");
陳述式。 - 新增
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
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 作用中的 Azure 通訊服務資源和連接字串。 建立通訊服務資源。
- 適用於您作業系統的作用中 LTS 和維修 LTS 版本 Node.js。
- 營運電話系統中工作階段邊界控制器 (SBC) 的完整網域名稱 (FQDN) 和連接埠號碼。
- SBC FQDN 經過驗證的網域名稱。
最終程式碼
在 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
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- Python 3.7+。
- 已部署的通訊服務資源和連接字串。 建立通訊服務資源。
- 營運電話系統中工作階段邊界控制器 (SBC) 的完整網域名稱 (FQDN) 和連接埠號碼。
- SBC FQDN 經過驗證的網域名稱。
最終程式碼
在 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_ID
、AZURE_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
清除資源
如果您想要清除並移除通訊服務訂用帳戶,您可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。 深入了解如何清除資源。
下一步
如需詳細資訊,請參閱下列文章:
- 了解通話自動化,以建置路由傳送和管理通訊服務通話的工作流程。
- 了解通話 SDK 功能。
- 深入了解通話的運作方式。
- 遵循快速入門,撥打電話號碼進行通話。