你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure 通信管理客户端库 - 版本 1.0.0-beta.3

项目
04/05/2023

管理库用于管理Azure 通信服务的用户和令牌。此库还提供电话号码管理功能。

获取的电话号码可以附带许多功能，具体取决于国家/地区、号码类型和电话计划。功能的示例包括短信入站和出站用法、PSTN 入站和出站用法。还可以通过 Webhook URL 将电话号码分配给机器人。

入门

先决条件

一个 Azure 订阅。
现有的通信服务资源。如果需要创建资源，可以使用 Azure 门户或 Azure CLI。

安装

npm install @azure/communication-administration

关键概念

客户端

管理包公开两个客户端。 CommunicationIdentityClient提供管理用户及其令牌的方法。 PhoneNumberAdministrationClient提供管理电话号码计划和号码的方法。

电话计划概述

电话计划有两种类型：地理和免费电话。地理电话套餐是与某个位置关联的电话套餐，其电话号码的区号与地理位置的区号相关联。 Toll-Free电话套餐不是关联位置的电话计划。例如，在美国，免费电话号码可以附带区号，例如 800 或 888。

同一国家/地区中的所有地理电话计划都分组到具有地理电话号码类型的电话计划组中。同一国家/地区中的所有Toll-Free电话计划都分组到一个电话计划组中。

搜索和获取号码

可以通过提供电话号码计划 ID、区号和电话号码数量，通过搜索创建 API 搜索电话号码。提供的电话号码数量将保留 10 分钟。可以取消或购买此电话号码搜索。如果取消搜索，则电话号码将变为可供其他人使用。如果购买了搜索，则会获取 Azure 资源的电话号码。

配置和分配号码

可以通过配置号码 API 将电话号码分配给回调 URL。在配置过程中，需要获取的电话号码、回调 URL 和应用程序 ID。

示例

身份验证

可以从 Azure 门户中的通信服务资源获取密钥和/或连接字符串。获得密钥后，可以使用以下任一方法对和 PhoneNumberAdministrationClient 进行身份验证CommunicationIdentityClient：

在初始化客户端之前使用 `AzureKeyCredential` 创建`KeyCredential`

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();

故障排除

后续步骤

有关如何使用此库的详细示例，请查看示例目录。

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

Microsoft Azure SDK for Javascript

曝光数

通过