Клиентская библиотека телефонных номеров связи Azure для JavaScript — версия 1.4.0

Библиотека номеров телефонов предоставляет возможности для администрирования номеров телефонов.

Приобретенные номера телефонов могут содержать множество возможностей в зависимости от страны, типа номера и типа назначения. Примерами возможностей являются входящий и исходящий трафик SMS, ТСОП входящего и исходящего использования. Номера телефонов также можно назначить боту по URL-адресу веб-перехватчика.

Начало работы

Предпосылки

• Подписка 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 создания поиска, указав тип номера телефона (географический или бесплатный), тип назначения (человек или приложение), возможности звонков и sms, код области и количество номеров телефонов. Предоставленное количество номеров телефонов будет зарезервировано в течение 15 минут. Этот поиск телефонных номеров можно отменить или приобрести. Если поиск отменен, номера телефонов будут доступны другим пользователям. Если поиск приобретен, для ресурса Azure будут приобретены номера телефонов.

Настройка номеров телефонов

Номера телефонов могут иметь сочетание возможностей. Они могут быть настроены для поддержки входящих и (или) исходящих звонков или ни в том случае, если вы не будете использовать номер телефона для звонков. Это же относится к возможностям sms.

Важно учитывать тип назначения номера телефона. Некоторые возможности ограничены определенным типом назначения.

Просмотр и резервирование номеров телефонов

API обзора и резервирования предоставляют альтернативный способ получения номеров телефонов с помощью корзины. Это достигается за счет разделения операции поиска, которая находит и резервирует номера с помощью одного LRO, на два отдельных синхронных шага: Обзор и Резервирование.

Операция просмотра извлекает случайную выборку телефонных номеров, доступных для покупки в данной стране, с необязательными критериями фильтрации для сужения результатов. Возвращенные номера телефонов не зарезервированы для клиентов.

Резервирование представляет собой набор телефонных номеров, заблокированных определенным клиентом и ожидающих покупки. Срок их действия составляет 15 минут после последней модификации или 2 часа с момента создания. Бронь может включать номера из разных стран, в отличие от операции Поиск. Клиенты могут создавать, извлекать, изменять (добавляя и удаляя номера), удалять и приобретать резервирования. Покупка резервирования является LRO.

Клиент маршрутизации SIP

Функция прямой маршрутизации позволяет подключать инфраструктуру телефонии, предоставляемую клиентом, к ресурсам связи Azure. Чтобы правильно настроить конфигурацию маршрутизации, клиенту необходимо предоставить правила маршрутизации магистрали SIP и SIP для вызовов. Клиент маршрутизации SIP предоставляет необходимый интерфейс для настройки этой конфигурации.

При вызове система пытается сопоставить целевой номер с шаблонами регулярных номеров определенных маршрутов. Будет выбран первый маршрут, соответствующий номеру. Порядок сопоставления регулярных выражений совпадает с порядком маршрутов в конфигурации, поэтому порядок маршрутов имеет значение. После сопоставления маршрута вызов направляется в первый магистраль в списке магистралей маршрута. Если магистраль недоступна, выбран следующий магистраль в списке.

Примеры

Аутентификация

Чтобы создать клиентский объект для доступа к API служб коммуникации, вам потребуется connection string или endpoint ресурс служб коммуникации и a 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 Active Directory с помощью библиотеки удостоверений Azure. Чтобы использовать поставщик defaultAzureCredential, показанный ниже, или другие поставщики учетных данных, предоставленные пакетом Azure SDK, установите пакет :

npm install @azure/identity

Пакет @azure/identity предоставляет различные типы учетных данных, которые приложение может использовать для этого. README для @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. Сценарии, описанные здесь, состоят из следующих:

PhoneNumbersКлиент

• Поиск доступных номеров телефонов
• Приобретение номеров телефонов из поиска
• Просмотр и резервирование доступных номеров телефонов
• Выпуск приобретенного номера телефона
• Обновление возможностей номера телефона
• Резервирование покупки
• Получение приобретенного номера телефона
• Вывод списка приобретенных номеров телефонов

SipRoutingClient (Клиент SipRoutingClient)

• Получение магистралей SIP и маршрутов
• Замена магистралей SIP и маршрутов
• Получение одной магистрали
• Установка одного магистрали
• Удаление одной магистрали

PhoneNumbersКлиент

Поиск доступных номеров телефонов

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 Используйте метод, чтобы приобрести номера телефонов из поиска. Приобретенные номера телефонов будут назначены ресурсу служб коммуникации, используемому при инициировании клиента. Возвращается searchId из beginSearchAvailablePhoneNumbers нее.

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]}`);

Просмотр и резервирование доступных номеров телефонов

Используйте API обзора и резервирования для резервирования номера телефона

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  BrowseAvailableNumbersRequest,
  AvailablePhoneNumber,
} from "@azure/communication-phone-numbers";

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

const browseAvailableNumberRequest: BrowseAvailableNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
};

const browseAvailableNumbers = await client.browseAvailablePhoneNumbers(
  browseAvailableNumberRequest,
  {
    capabilities: {
      calling: "outbound",
    },
    assignmentType: "application",
  },
);
const phoneNumbers = browseAvailableNumbers.phoneNumbers;
const phoneNumbersList = [phoneNumbers[0], phoneNumbers[1]];
const reservationResponse = await client.createOrUpdateReservation(
  {
    reservationId: "reservationId",
  },
  {
    add: phoneNumbersList,
  },
);
const numbersWithError: AvailablePhoneNumber[] = [];
for (const number of Object.values(reservationResponse.phoneNumbers || {})) {
  if (number != null && number.status === "error") {
    numbersWithError.push(number);
  }
}
if (numbersWithError.length > 0) {
  console.log("Errors occurred during reservation");
} else {
  console.log("Reservation operation completed without errors.");
}

Выпуск приобретенного номера телефона

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 Используйте метод для обновления возможностей приобретенного номера телефона. Номера телефонов можно настроить для поддержки входящих и (или) исходящих звонков и sms или ни для того, ни другого.

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}`);

Резервирование покупки

При наличии существующего и активного бронирования приобретите номера телефонов в этом резервировании.

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 reservationId = "<reservation-id>";

const purchasePoller = await client.beginReservationPurchase(reservationId);

// Purchase is underway.
const purchaseResult = await purchasePoller.pollUntilDone();
console.log(`Successfully purchased phone numbers in reservation: ${reservationId}`);

Вывод списка приобретенных номеров телефонов

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 (Клиент 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. В альтернативном порядке, логирование можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Дальнейшие шаги

Ознакомьтесь с примерами каталога, чтобы получить подробные примеры использования этой библиотеки.

Вклад

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.

Связанные проекты

• Пакет SDK Microsoft Azure для JavaScript