適用於 JavaScript 的 Azure 通訊電話號碼用戶端連結庫 - 1.3.0 版
電話號碼連結庫提供電話號碼管理的功能。
購買的電話號碼可以隨附許多功能，視國家/地區、號碼類型和指派類型而定。 功能的範例包括SMS輸入和輸出使用方式、PSTN 輸入和輸出使用量。 電話號碼也可以透過 Webhook URL 指派給 Bot。
開始
先決條件
- Azure 訂用帳戶。
- 現有的通訊服務資源。 如果您需要建立資源，您可以使用 Azure 入口網站、Azure PowerShell或 Azure CLI。
安裝
npm install @azure/communication-phone-numbers
瀏覽器支援
JavaScript 套件組合
若要在瀏覽器中使用此用戶端連結庫，您必須先使用配套程式。 如需如何執行這項作的詳細資訊，請參閱我們的 組合檔。
重要概念
此 SDK 提供輕鬆管理 direct offer 和 direct routing 數位的功能。
direct offer 數位有兩種類型：地理和免付費電話。 地理電話方案是與某個位置相關聯的電話方案，其電話號碼的區域代碼與地理位置的區域代碼相關聯。 Toll-Free 電話方案是電話方案沒有關聯的位置。 例如，在美國，免付費電話號碼可以隨附區域代碼，例如 800 或 888。
它們是使用 PhoneNumbersClient 管理
direct routing 功能可讓您將現有的電話語音基礎結構連線到ACS。
組態是使用 SipRoutingClient來管理，其提供設定SIP主幹和語音路由規則的方法，以便正確處理電話語音子網的通話。
電話號碼用戶端
電話號碼類型
電話號碼有兩種類型：地理和免付費。 地理電話號碼是與位置相關聯的電話號碼，其區域代碼與地理位置的區域代碼相關聯。 Toll-Free 電話號碼與位置無關。 例如，在美國，免付費電話號碼可以隨附區域代碼，例如 800 或 888。
相同國家/地區的所有地理電話號碼都會分組為具有地理電話號碼類型的電話方案群組。 相同國家/地區的所有 Toll-Free 電話號碼都會分組為電話方案群組。
搜尋和取得數位
您可以透過搜尋建立 API 來搜尋電話號碼，方法是提供電話號碼類型（地理或免付費電話）、指派類型（人員或應用程式）、通話和簡訊功能、區域代碼和電話號碼數量。 提供的電話號碼數量將保留 15 分鐘。 您可以取消或購買此電話號碼搜尋。 如果搜尋已取消，則電話號碼將可供其他人使用。 如果已購買搜尋，則會取得 Azure 資源的電話號碼。
設定電話號碼
電話號碼可以有功能的組合。 它們可以設定為支援輸入和/或撥出通話，或者如果您不會使用電話號碼進行通話，則兩者都無法進行。 同樣適用於簡訊功能。
請務必考慮電話號碼的指派類型。 某些功能僅限於特定指派類型。
SIP 路由用戶端
直接路由功能允許將客戶提供的電話語音基礎結構連線至 Azure 通訊資源。 為了正確設定路由設定，客戶必須提供 SIP 主幹組態和 SIP 路由規則以進行通話。 SIP 路由用戶端提供設定此組態的必要介面。
進行呼叫時，系統會嘗試比對目的地號碼與已定義路由的 regex 號碼模式。 要比對數位的第一個路由將會選取。 regex 比對的順序與組態中的路由順序相同，因此路由順序很重要。 比對路由之後，呼叫就會路由至路由主幹清單中的第一個主幹。 如果主幹無法使用，則會選取清單中的下一個主幹。
例子
認證
若要建立客戶端物件以存取通訊服務 API，您需要 connection string 或通訊服務資源的 endpoint，以及 credential。 電話號碼用戶端可以使用 Azure Active Directory 認證或 API 金鑰認證來進行驗證。
您可以在 Azure 入口網站中，從通訊服務資源取得金鑰和/或連接字串。 您也可以在 Azure 入口網站中找到通訊服務資源的端點。
擁有金鑰之後，您可以使用下列任一方法驗證用戶端：
使用連接字串
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";
const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new SipRoutingClient(connectionString);
搭配使用存取金鑰搭配 AzureKeyCredential
如果您使用金鑰來初始化用戶端，則也需要提供適當的端點。 您可以從 Azure 入口網站中的通訊服務資源取得此端點，。 擁有金鑰和端點之後，您就可以使用下列程式代碼進行驗證：
import { AzureKeyCredential } from "@azure/core-auth";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";
const credential = new AzureKeyCredential("<key-from-resource>");
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
import { AzureKeyCredential } from "@azure/core-auth";
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const credential = new AzureKeyCredential("<key-from-resource>");
const client = new SipRoutingClient("<endpoint-from-resource>", credential);
使用 Azure Active Directory 認證
大部分範例都使用連接字串驗證，但您也可以使用 Azure 身分識別連結庫向 Azure Active Directory 進行驗證。 若要使用如下所示的 DefaultAzureCredential 提供者，或 Azure SDK 所提供的其他認證提供者，請安裝 @azure/identity 套件：
npm install @azure/identity
@azure/identity 套件提供應用程式可用來執行這項作業的各種認證類型。
@azure/identity
的 自述檔提供更多詳細數據和範例，讓您開始使用。
import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);
用法
下列各節提供代碼段，這些代碼段涵蓋使用 Azure 通訊服務電話號碼用戶端的一些常見工作。 這裡涵蓋的案例包括：
PhoneNumbersClient
SipRoutingClient
PhoneNumbersClient
搜尋可用的電話號碼
使用 beginSearchAvailablePhoneNumbers 方法來搜尋電話號碼並保留電話號碼。 傳回的電話號碼會保留 15 分鐘，而且可以透過將 searchId 提供給 beginPurchasePhoneNumbers 方法，在此期間內購買。
beginSearchAvailablePhoneNumbers 是長時間執行的作業，並傳迴輪詢器。
import { DefaultAzureCredential } from "@azure/identity";
import {
PhoneNumbersClient,
SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
const searchRequest: SearchAvailablePhoneNumbersRequest = {
countryCode: "US",
phoneNumberType: "tollFree",
assignmentType: "application",
capabilities: {
sms: "outbound",
calling: "none",
},
quantity: 1,
};
const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);
// The search is underway. Wait to receive searchId.
const searchResults = await searchPoller.pollUntilDone();
console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
console.log(`searchId: ${searchResults.searchId}`);
從搜尋購買電話號碼
使用 beginPurchasePhoneNumbers 方法來從您的搜尋中購買電話號碼。 購買的電話號碼將會指派給起始用戶端時所使用的通訊服務資源。 需要從 beginSearchAvailablePhoneNumbers 傳回的 searchId。
beginPurchasePhoneNumbers 是長時間執行的作業，並傳迴輪詢器。
import { DefaultAzureCredential } from "@azure/identity";
import {
PhoneNumbersClient,
SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
const searchRequest: SearchAvailablePhoneNumbersRequest = {
countryCode: "US",
phoneNumberType: "tollFree",
assignmentType: "application",
capabilities: {
sms: "outbound",
calling: "none",
},
quantity: 1,
};
const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);
// The search is underway. Wait to receive searchId.
const { searchId, phoneNumbers } = await searchPoller.pollUntilDone();
const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);
// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumbers[0]}`);
釋出已購買的電話號碼
使用 beginReleasePhoneNumber 方法來釋放先前購買的電話號碼。 已發行的電話號碼將不再與通訊服務資源相關聯，且無法與其他作業搭配使用（例如。資源的SMS。 需要釋放的電話號碼。
beginReleasePhoneNumber 是長時間執行的作業，並傳迴輪詢器。
import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
const phoneNumberToRelease = "<phone-number-to-release>";
const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);
// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");
更新電話號碼功能
使用 beginUpdatePhoneNumberCapabilities 方法來更新已購買電話號碼的功能。 電話號碼可以設定為支援輸入和/或輸出通話和簡訊，或兩者都不支援。
beginUpdatePhoneNumberCapabilities 是長時間執行的作業，並傳迴輪詢器。
import { DefaultAzureCredential } from "@azure/identity";
import {
PhoneNumbersClient,
PhoneNumberCapabilitiesRequest,
} from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
const phoneNumberToUpdate = "<phone-number-to-update>";
// This will update phone number to send and receive sms, but only send calls.
const updateRequest: PhoneNumberCapabilitiesRequest = {
sms: "inbound+outbound",
calling: "outbound",
};
const updatePoller = await client.beginUpdatePhoneNumberCapabilities(
phoneNumberToUpdate,
updateRequest,
);
// Update is underway.
const { capabilities } = await updatePoller.pollUntilDone();
console.log(`These are the update capabilities: ${capabilities}`);
取得購買的電話號碼
使用 getPurchasedPhoneNumber 方法來取得已購買電話號碼的相關信息。 此資訊包括電話號碼的類型、功能、成本和購買日期。
import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
const phoneNumberToGet = "<phone-number-to-get>";
const phoneNumber = await client.getPurchasedPhoneNumber(phoneNumberToGet);
console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);
列出已購買的電話號碼
使用 listPurchasedPhoneNumbers 方法來逐頁查看所有已購買的電話號碼。
import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);
const phoneNumbers = client.listPurchasedPhoneNumbers();
for await (const phoneNumber of phoneNumbers) {
console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);
}
SipRoutingClient
擷取 SIP 主幹和路由
取得目前設定的主幹或路由清單。
import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);
const trunks = client.listTrunks();
const routes = client.listRoutes();
for await (const trunk of trunks) {
console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
}
for await (const route of routes) {
console.log(`Route ${route.name} with pattern ${route.numberPattern}`);
console.log(`Route's trunks: ${route.trunks?.join()}`);
}
取代 SIP 主幹和路由
以新值取代目前設定的主幹或路由清單。
import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);
await client.setTrunks([
{
fqdn: "sbc.one.domain.com",
sipSignalingPort: 1234,
},
{
fqdn: "sbc.two.domain.com",
sipSignalingPort: 1234,
},
]);
await client.setRoutes([
{
name: "First Route",
description: "route's description",
numberPattern: "^+[1-9][0-9]{3,23}$",
trunks: ["sbc.one.domain.com"],
},
{
name: "Second Route",
description: "route's description",
numberPattern: "^.*$",
trunks: ["sbc.two.domain.com", "sbc.one.domain.com"],
},
]);
擷取單一主
import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);
const trunk = await client.getTrunk("sbc.one.domain.com");
if (trunk) {
console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
} else {
console.log("Trunk not found");
}
設定單一主幹
import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);
await client.setTrunk({
fqdn: "sbc.one.domain.com",
sipSignalingPort: 4321,
});
刪除單一主幹
import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";
const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);
await client.deleteTrunk("sbc.one.domain.com");
故障排除
伐木
啟用記錄可能有助於找出有關失敗的實用資訊。 若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在運行時間啟用記錄，方法是在 @azure/logger中呼叫 setLogLevel：
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
如需如何啟用記錄的詳細指示，請參閱 @azure/記錄器套件檔。
後續步驟
如需如何使用此連結庫的詳細範例，請參閱 範例 目錄。
貢獻
如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。
