共用方式為

適用于 JavaScript 的 Azure 通訊管理用戶端程式庫 - 1.0.0-Beta.3 版

  • 發行項

管理程式庫用於管理Azure 通訊服務的使用者和權杖。 此程式庫也提供電話號碼管理的功能。

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

開始使用

Prerequisites

安裝

npm install @azure/communication-administration

重要概念

用戶端

系統管理套件會公開兩個用戶端。 提供 CommunicationIdentityClient 管理使用者及其權杖的方法。 提供 PhoneNumberAdministrationClient 方法來管理電話號碼和號碼。

電話方案概觀

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

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

搜尋和取得數位

您可以透過搜尋建立 API 來搜尋電話號碼，方法是提供電話號碼方案識別碼、區功能變數代碼和電話號碼數量。 提供的電話號碼數量將會保留 10 分鐘。 您可以取消或購買此電話號碼搜尋。 如果搜尋已取消，則電話號碼將可供其他人使用。 如果已購買搜尋，則會取得 Azure 資源的電話號碼。

設定和指派數位

電話號碼可以透過設定號碼 API 指派給回呼 URL。 在設定過程中，您將需要取得的電話號碼、回呼 URL 和應用程式識別碼。

範例

驗證

您可以從 Azure入口網站中的通訊服務資源取得金鑰和/或連接字串。 取得金鑰之後，您可以使用下列任何方法驗證 CommunicationIdentityClient 和 PhoneNumberAdministrationClient ：

在初始化用戶端之前先建立 KeyCredentialAzureKeyCredential

import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-administration";

const credential = new AzureKeyCredential(KEY);
const client = new CommunicationIdentityClient(HOST, credential);

使用連接字串

import { PhoneNumberAdministrationClient } from "@azure/communication-administration";

const connectionString = `endpoint=HOST;accessKey=KEY`;
const client = new CommunicationIdentityClient(connectionString);

如果您使用金鑰來初始化用戶端，您也需要提供適當的端點。 您可以從 Azure入口網站中的通訊服務資源取得此端點。

使用方式

CommunicationIdentityClient

建立 CommunicationIdentityClient 的實例

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

建立新使用者

createUser使用 方法來建立新的使用者。

const user = await client.createUser();

建立及重新整理使用者權杖

issueToken使用 方法來發行或重新整理現有使用者的權杖。 方法也會採用通訊權杖範圍清單。 範圍選項包括：

  • chat (聊天)
  • pstn (公用交換電話網路)
  • voip (透過 IP 的語音) 
let { token } = await client.issueToken(user, ["chat"]);

若要重新整理使用者權杖，請使用相同的使用者發行另一個權杖。

{ token } = await client.issueToken(user, ["chat"]);

撤銷使用者的權杖

revokeTokens使用 方法來撤銷使用者的所有已發行權杖。

await client.revokeTokens(user);

revokeTokens接受選擇性的第二個引數 。 tokensValidFrom 如果提供此日期， revokeTokens 將會撤銷之前發行的所有權杖。 否則，將會撤銷所有權杖。

正在刪除使用者

deleteUser使用 方法來刪除使用者。

await client.deleteUser(user);

PhoneNumberAdministrationClient

建立 PhoneNumberAdministrationClient 的實例

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

取得國家/地區

listSupportedCountries使用 方法來取得支援的國家/地區清單。

const countries = await client.listSupportedCountries();

for await (const country of countries) {
  console.log(`Country code: ${country.countryCode}`);
  console.log(`Country name: ${country.localizedName}`);
}

取得電話方案群組

電話方案群組有兩種類型：地理和免付費電話。 listPhonePlanGroups使用 方法來取得它們。

const countryCode = "US";
const phonePlanGroups = await client.listPhonePlanGroups(countryCode);

for await (const phonePlanGroup of phonePlanGroups) {
  console.log(`Phone plan group id: ${phonePlanGroup.phonePlanGroupId}`);
}

取得位置選項

針對地理電話方案，您可以查詢可用的地理位置。 位置選項的結構類似國家/地區的地理階層。 例如，美國有州，且每個州內都是城市。

getPhonePlanLocationOptions使用 方法來取得位置的選項。

const { locationOptions } = await client.getPhonePlanLocationOptions({
  countryCode: "US",
  phonePlanGroupId: "phonePlanGroupId",
  phonePlanId: "phonePlanId"
});

console.log(`Got location options for: ${locationOptions.labelId}`);

取得區功能變數代碼

擷取地理電話方案的區功能變數代碼將需要設定位置選項查詢。 您必須包含周遊位置選項物件所傳 getPhonePlanLocationOptions 回的地理位置鏈結。

getAreaCodes使用 方法來取得地理電話方案的區功能變數代碼。

const { primaryAreaCodes } = await client.getAreaCodes({
  locationType: "selection",
  countryCode: "US",
  phonePlanId: "phonePlanId",
  locationOptionsQueries
});

保留電話號碼以供購買

beginReservePhoneNumbers使用 方法來搜尋電話號碼並保留電話號碼。 這是長時間執行的作業。

const reservePoller = await client.beginReservePhoneNumbers({
    name: "Phone number search 800",
    description: "Search for 800 phone numbers"
    phonePlanIds: ["phone-plan-id-1"],
    areaCode: "800",
    quantity: 3
});

若要取得保留的結果，請在 pollUntilDone 您所建立的輪詢器上使用 方法。

const phoneNumberReservation = await reservePoller.pollUntilDone();

您可以在您所建立的輪詢器上呼叫 cancelOperation 方法來取消輪詢和保留。

await reservePoller.cancelOperation();

從保留購買電話號碼

beginPurchasePhoneNumbers使用 方法來從您的保留購買電話號碼。 需要 reservationId 從 beginReservePhoneNumbers 傳回的 。 beginPurchasePhoneNumbers 也是長時間執行的作業。

const { reservationId } = phoneNumberReservation;
const purchasePoller = await client.beginPurchasePhoneNumbers(reservationId);

若要取得購買的結果，請在 pollUntilDone 您所建立的購買輪詢器上使用 方法。

const results = await purchasePoller.pollUntilDone();

疑難排解

後續步驟

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

參與

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

曝光數