Udostępnij za pośrednictwem

Biblioteka klienta numerów telefonów komunikacyjnych platformy Azure dla języka JavaScript — wersja 1.4.0

Biblioteka numerów telefonów zapewnia możliwości administracji numerami telefonów.

Zakupione numery telefonów mogą mieć wiele możliwości, w zależności od kraju, typu numeru i typu przypisania. Przykłady możliwości to użycie ruchu przychodzącego i wychodzącego sms, użycie ruchu przychodzącego i wychodzącego PSTN. Numery telefonów można również przypisać do bota za pośrednictwem adresu URL elementu webhook.

Wprowadzenie

Warunki wstępne

  • Subskrypcja platformy Azure .
  • Istniejący zasób usług komunikacyjnych. Jeśli musisz utworzyć zasób, możesz użyć witryny Azure Portal, programu Azure PowerShelllub interfejsu wiersza polecenia platformy Azure .

Instalowanie

npm install @azure/communication-phone-numbers

Obsługa przeglądarki

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

Kluczowe pojęcia

Ten zestaw SDK umożliwia łatwe zarządzanie direct offer i direct routing numerami.

Liczby direct offer są dostępne w dwóch typach: geograficznym i bezpłatnym. Geograficzne plany telefonów to plany telefoniczne skojarzone z lokalizacją, której numery telefonów są skojarzone z kodem obszaru lokalizacji geograficznej. Toll-Free plany telefoniczne to plany telefoniczne, które nie są skojarzone z lokalizacją. Na przykład w Stanach Zjednoczonych numery bezpłatne mogą zawierać kody obszarów, takie jak 800 lub 888. Są one zarządzane przy użyciu PhoneNumbersClient

Funkcja direct routing umożliwia łączenie istniejącej infrastruktury telefonii z usługą ACS. Konfiguracja jest zarządzana przy użyciu SipRoutingClient, która udostępnia metody konfigurowania magistrali SIP i reguł routingu głosowego, aby prawidłowo obsługiwać wywołania podsieci telefonii.

Klient numerów telefonów

Typy numerów telefonów

Numery telefonów są dostępne w dwóch typach; Geograficzne i bezpłatne. Geograficzne numery telefonów to numery telefonów skojarzone z lokalizacją, której kody obszaru są skojarzone z kodem obszaru lokalizacji geograficznej. Toll-Free numery telefonów nie są skojarzone z lokalizacją. Na przykład w Stanach Zjednoczonych numery bezpłatne mogą zawierać kody obszarów, takie jak 800 lub 888.

Wszystkie geograficzne numery telefonów w tym samym kraju są pogrupowane w grupę planów telefonicznych z typem numeru telefonu geograficznego. Wszystkie Toll-Free numery telefonów w tym samym kraju są pogrupowane w grupę planów telefonicznych.

Wyszukiwanie i uzyskiwanie liczb

Numery telefonów można przeszukiwać za pośrednictwem interfejsu API tworzenia wyszukiwania, podając typ numeru telefonu (geograficzny lub bezpłatny), typ przypisania (osoba lub aplikacja), możliwości połączeń i wiadomości SMS, kod obszaru i ilość numerów telefonów. Podana ilość numerów telefonów będzie zarezerwowana przez 15 minut. To wyszukiwanie numerów telefonów może zostać anulowane lub zakupione. Jeśli wyszukiwanie zostanie anulowane, numery telefonów staną się dostępne dla innych osób. Jeśli wyszukiwanie zostanie zakupione, numery telefonów zostaną uzyskane dla zasobu platformy Azure.

Konfigurowanie numerów telefonów

Numery telefonów mogą mieć kombinację możliwości. Można je skonfigurować pod kątem obsługi połączeń przychodzących i/lub wychodzących albo nie, jeśli nie użyjesz numeru telefonu do nawiązywania połączeń. To samo dotyczy możliwości wiadomości SMS.

Ważne jest, aby wziąć pod uwagę typ przypisania numeru telefonu. Niektóre możliwości są ograniczone do określonego typu przypisania.

Przeglądanie i rezerwowanie numerów telefonów

Interfejsy API przeglądania i rezerwacji zapewniają alternatywny sposób uzyskiwania numerów telefonów za pomocą środowiska podobnego do koszyka na zakupy. Osiąga się to poprzez podzielenie operacji wyszukiwania, która znajduje i rezerwuje numery przy użyciu jednego LRO, na dwa oddzielne kroki synchroniczne: Przeglądaj i Rezerwacja.

Operacja przeglądania pobiera losową próbkę numerów telefonów, które są dostępne do zakupu dla danego kraju, z opcjonalnymi kryteriami filtrowania w celu zawężenia wyników. Zwrócone numery telefonów nie są zarezerwowane dla żadnego klienta.

Rezerwacje to zbiór numerów telefonów, które są zablokowane przez określonego klienta i oczekują na zakup. Mają czas wygaśnięcia 15 minut po ostatniej modyfikacji lub 2 godziny od momentu utworzenia. Rezerwacja może zawierać numery z różnych krajów, w przeciwieństwie do operacji wyszukiwania. Klienci mogą tworzyć, pobierać, modyfikować (dodając i usuwając numery), usuwać i kupować rezerwacje. Zakup rezerwacji jest LRO.

Klient routingu SIP

Funkcja routingu bezpośredniego umożliwia łączenie infrastruktury telefonii dostarczonej przez klienta z zasobami usługi Azure Communication. Aby prawidłowo skonfigurować konfigurację routingu, klient musi podać konfigurację magistrali SIP i reguły routingu SIP dla wywołań. Klient routingu SIP udostępnia niezbędny interfejs do ustawienia tej konfiguracji.

Po wywołaniu system próbuje dopasować numer docelowy do wzorców numerów wyrażeń regularnych zdefiniowanych tras. Zostanie wybrana pierwsza trasa zgodna z liczbą. Kolejność dopasowywania wyrażeń regularnych jest taka sama jak kolejność tras w konfiguracji, dlatego kolejność tras ma znaczenie. Po dopasowaniu trasy wywołanie jest kierowane do pierwszego magistrali na liście magistrali trasy. Jeśli magistrala jest niedostępna, zostanie wybrana następna magistrala na liście.

Przykłady

Uwierzytelnianie

Aby utworzyć obiekt klienta w celu uzyskania dostępu do interfejsu API usług komunikacyjnych, potrzebny będzie connection string lub endpoint zasobu usług komunikacyjnych oraz credential. Klient numerów telefonów może używać poświadczeń usługi Azure Active Directory lub poświadczeń klucza interfejsu API do uwierzytelniania.

Klucz i/lub parametry połączenia można uzyskać z zasobu usług Communication Services w witrynie Azure Portal. Punkt końcowy zasobu usług komunikacyjnych można również znaleźć w witrynie Azure Portal.

Po utworzeniu klucza możesz uwierzytelnić klienta przy użyciu dowolnej z następujących metod:

Używanie parametrów połączenia

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

Używanie klucza dostępu z AzureKeyCredential

Jeśli używasz klucza do inicjowania klienta, musisz również podać odpowiedni punkt końcowy. Ten punkt końcowy można uzyskać z zasobu usług Komunikacyjnych w witrynie Azure Portal. Po utworzeniu klucza i punktu końcowego możesz uwierzytelnić się przy użyciu następującego kodu:

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

Używanie poświadczeń usługi Azure Active Directory

Uwierzytelnianie parametrów połączenia jest używane w większości przykładów, ale można również uwierzytelnić się w usłudze Azure Active Directory przy użyciu biblioteki Azure Identity library. Aby użyć dostawcy DefaultAzureCredential pokazanego poniżej lub innych dostawców poświadczeń dostarczonych z zestawem Azure SDK, zainstaluj pakiet @azure/identity:

npm install @azure/identity

Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. Plik README dla @azure/identity zawiera więcej szczegółów i przykładów, które ułatwiają rozpoczęcie pracy.

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

Zwyczaj

Poniższe sekcje zawierają fragmenty kodu, które obejmują niektóre typowe zadania przy użyciu klienta numerów telefonów usług Azure Communication Services. Scenariusze, które zostały tutaj omówione, składają się z następujących elementów:

PhoneNumbersClient (NumeryTelefonów)

SipRoutingClient

PhoneNumbersClient (NumeryTelefonów)

Wyszukaj dostępne numery telefonów

Użyj metody beginSearchAvailablePhoneNumbers, aby wyszukać numery telefonów i zarezerwować je. Zwrócone numery telefonów są zarezerwowane przez 15 minut i można je kupić w tym okresie, podając searchId metodę beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers jest długotrwałą operacją i zwraca poller.

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

Użyj metody beginPurchasePhoneNumbers, aby kupić numery telefonów z wyszukiwania. Zakupione numery telefonów zostaną przypisane do zasobu usług komunikacyjnych używanego podczas inicjowania klienta. Wymagany jest searchId zwrócony z beginSearchAvailablePhoneNumbers.

beginPurchasePhoneNumbers jest długotrwałą operacją i zwraca poller.

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

Przeglądaj i rezerwuj dostępne numery telefonów

Korzystanie z interfejsu API przeglądania i rezerwacji w celu zarezerwowania numeru telefonu

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.");
}

Zwolnienie zakupionego numeru telefonu

Użyj metody beginReleasePhoneNumber, aby zwolnić wcześniej zakupiony numer telefonu. Opublikowane numery telefonów nie będą już skojarzone z zasobem usług komunikacyjnych i nie będą dostępne do użycia z innymi operacjami (np. WIADOMOŚĆ SMS) zasobu. Wymagany jest numer telefonu, który jest zwalniany.

beginReleasePhoneNumber jest długotrwałą operacją i zwraca poller.

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.");

Aktualizowanie możliwości numeru telefonu

Użyj metody beginUpdatePhoneNumberCapabilities, aby zaktualizować możliwości zakupionego numeru telefonu. Numery telefonów można skonfigurować tak, aby obsługiwały połączenia przychodzące i/lub wychodzące oraz wiadomości SMS lub nie.

beginUpdatePhoneNumberCapabilities jest długotrwałą operacją i zwraca poller.

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

Uzyskiwanie zakupionego numeru telefonu

Użyj metody getPurchasedPhoneNumber, aby uzyskać informacje o zakupionym numerze telefonu. Te informacje obejmują typ, możliwości, koszty i datę zakupu numeru telefonu.

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

Rezerwacja zakupu

Biorąc pod uwagę istniejącą i aktywną rezerwację, kup numery telefonów w tej rezerwacji.

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

Wyświetlanie listy zakupionych numerów telefonów

Użyj metody listPurchasedPhoneNumbers, aby stronicować wszystkie zakupione numery telefonów.

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

Pobieranie magistrali SIP i tras

Pobierz listę aktualnie skonfigurowanych magistrali lub tras.

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

Wymiana magistrali SIP i tras

Zastąp listę aktualnie skonfigurowanych magistrali lub tras nowymi wartościami.

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

Pobieranie pojedynczego magistrali

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

Ustawianie pojedynczego magistrali

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

Usuwanie pojedynczego magistrali

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

Rozwiązywanie problemów

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Następne kroki

Zapoznaj się z przykładami katalogu, aby zapoznać się ze szczegółowymi przykładami dotyczącymi korzystania z tej biblioteki.

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.