適用于 JavaScript 的 Azure 通訊電話號碼用戶端程式庫 - 1.0.0 版

電話號碼程式庫提供電話號碼管理的功能。

購買的電話號碼可以隨附許多功能，視國家/地區、號碼類型和指派類型而定。 功能的範例包括 SMS 輸入和輸出使用量、PSTN 輸入和輸出使用量。 電話號碼也可以透過 Webhook URL 指派給 Bot。

開始使用

Prerequisites

• Azure 訂用帳戶。
• 現有的通訊服務資源。 如果您需要建立資源，您可以使用Azure 入口網站、Azure PowerShell或Azure CLI。

安裝

npm install @azure/communication-phone-numbers

瀏覽器支援

JavaScript 套件組合

若要在瀏覽器中使用此用戶端程式庫，您必須先使用套件組合器。 如需如何執行這項操作的詳細資訊，請參閱我們的 統合檔。

重要概念

電話號碼套件會公開 ， PhoneNumbersClient 其提供管理電話號碼的方法。

電話號碼類型

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

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

搜尋和取得數位

您可以透過搜尋建立 API 來搜尋電話號碼，方法是提供電話號碼類型 (地理或免付費) 、指派類型 (個人或應用程式) 、通話和簡訊功能、區域網路碼和電話號碼數量。 提供的電話號碼數量將會保留 15 分鐘。 您可以取消或購買此電話號碼搜尋。 如果搜尋已取消，則電話號碼將可供其他人使用。 如果已購買搜尋，則會取得 Azure 資源的電話號碼。

設定電話號碼

電話號碼可以結合功能。 它們可以設定為支援輸入和/或撥出通話，或者，如果您不會使用電話號碼進行通話，則都不能。 這也適用于簡訊功能。

請務必考慮電話號碼的指派類型。 某些功能僅限於特定指派類型。

範例

驗證

若要建立用戶端物件來存取通訊服務 API，您需要 connection string 或 endpoint 通訊服務資源的 和 credential 。 電話號碼用戶端可以使用 Azure Active Directory 認證或 API 金鑰認證進行驗證。

您可以從 Azure入口網站中的通訊服務資源取得金鑰和/或連接字串。 您也可以在 Azure入口網站中找到通訊服務資源的端點。

取得金鑰之後，您可以使用下列任何方法驗證 PhoneNumbersClient ：

使用連接字串

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(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);

使用 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";

let credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

使用方式

下列各節提供程式碼片段，這些程式碼片段涵蓋使用 Azure 通訊服務 電話號碼用戶端的一些常見工作。 這裡涵蓋的案例包括：

• 搜尋可用的電話號碼
• 從搜尋購買電話號碼
• 釋放購買的電話號碼
• 更新電話號碼功能
• 取得購買的電話號碼
• 列出已購買的電話號碼

搜尋可用的電話號碼

beginSearchAvailablePhoneNumbers使用 方法來搜尋電話號碼並保留電話號碼。 傳回的電話號碼會保留 15 分鐘，而且可以透過向 方法提供 searchId 來 beginPurchasePhoneNumbers 購買此期間。

beginSearchAvailablePhoneNumbers 是長時間執行的作業，並傳回輪詢器。

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const searchRequest = {
    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 = searchPoller.pollUntilDone();
  console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
  console.log(`searchId: ${searchResults.searchId}`);
}

main();

從搜尋購買電話號碼

beginPurchasePhoneNumbers使用 方法來從您的搜尋購買電話號碼。 購買的電話號碼將會指派給起始用戶端時所使用的通訊服務資源。 需要 searchId 從 beginSearchAvailablePhoneNumbers 傳回的 。

beginPurchasePhoneNumbers 是長時間執行的作業，並傳回輪詢器。

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const searchRequest = {
    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 } = searchPoller.pollUntilDone();

  const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

  // Purchase is underway.
  await purchasePoller.pollUntilDone();
  console.log(`Successfully purchased ${phoneNumbers[0]}`);
}

main();

釋放購買的電話號碼

beginReleasePhoneNumber使用 方法來釋放先前購買的電話號碼。 發行的電話號碼將不再與通訊服務資源相關聯，而且無法與其他作業搭配使用 (，例如：資源的 SMS) 。 需要釋放的電話號碼。

beginReleasePhoneNumber 是長時間執行的作業，並傳回輪詢器。

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const phoneNumberToRelease = "<phone-number-to-release>";

  const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

  // Release is underway.
  await releasePoller.pollUntilDone();
  console.log("Successfully release phone number.");
}

main();

更新電話號碼功能

beginUpdatePhoneNumberCapabilities使用 方法來更新已購買電話號碼的功能。 電話號碼可以設定為支援輸入和/或撥出通話和簡訊，或兩者皆否。

beginUpdatePhoneNumberCapabilities 是長時間執行的作業，並傳回輪詢器。

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const phoneNumberToUpdate = "<phone-number-to-update>";

  // This will update phone number to send and receive sms, but only send calls.
  const updateRequest = {
    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}`);
}

main();

取得購買的電話號碼

getPurchasedPhoneNumber使用 方法來取得已購買電話號碼的相關資訊。 此資訊包括電話號碼的類型、功能、成本和購買日期。

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async main function() {
  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}`);
}

main();

列出已購買的電話號碼

listPurchasedPhoneNumbers使用 方法來逐頁流覽所有購買的電話號碼。

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async main function() {
  const phoneNumbers = await 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}`);
  }
}

main();

疑難排解

後續步驟

如需如何使用此程式庫的詳細 範例 ，請參閱範例目錄。

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

相關專案

• Microsoft Azure SDK for JAVAscript