Delen via

Azure Communication-clientbibliotheek voor telefoonnummers voor JavaScript - versie 1.5.0

De bibliotheek met telefoonnummers biedt mogelijkheden voor het beheer van telefoonnummers.

Aangeschafte telefoonnummers kunnen worden geleverd met veel mogelijkheden, afhankelijk van het land, het nummertype en het toewijzingstype. Voorbeelden van mogelijkheden zijn inkomend en uitgaand sms-gebruik, inkomend en uitgaand PSTN-gebruik. Telefoonnummers kunnen ook worden toegewezen aan een bot via een webhook-URL.

Slag

Voorwaarden

Installeren

npm install @azure/communication-phone-numbers

Browserondersteuning

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

Sleutelbegrippen

Deze SDK biedt functionaliteit om eenvoudig direct offer en direct routing getallen te beheren.

De direct offer nummers zijn er in drie soorten: Geografisch, Toll-Free en Mobiel. Geografische en mobiele telefoonabonnementen zijn telefoonabonnementen die zijn gekoppeld aan een locatie waarvan de netnummers van telefoonnummers zijn gekoppeld aan het netnummer van een geografische locatie. Toll-Free telefoonabonnementen zijn geen gekoppelde locatie. In de VS kunnen bijvoorbeeld gratis nummers worden geleverd met netnummers zoals 800 of 888. Ze worden beheerd met behulp van de PhoneNumbersClient

Met de functie direct routing kunt u uw bestaande telefonie-infrastructuur verbinden met ACS. De configuratie wordt beheerd met behulp van de SipRoutingClient, die methoden biedt voor het instellen van SIP-trunks en spraakrouteringsregels om oproepen voor uw telefoniesubnet correct te verwerken.

Client met telefoonnummers

Typen telefoonnummers

Telefoonnummers zijn er in drie soorten; Geografisch, Toll-Free en mobiel. Toll-Free nummers zijn niet gekoppeld aan een locatie. In de VS kunnen bijvoorbeeld gratis nummers worden geleverd met netnummers zoals 800 of 888. Geografische en mobiele telefoonnummers zijn telefoonnummers die aan een locatie zijn gekoppeld.

Telefoonnummertypen met hetzelfde land worden gegroepeerd in een telefoonplangroep met dat telefoonnummertype. Alle Toll-Free telefoonnummers in hetzelfde land zijn bijvoorbeeld gegroepeerd in een telefoonabonnement.

Getallen zoeken en verkrijgen

Telefoonnummers kunnen worden doorzocht via de API voor het maken van zoekopdrachten door een type telefoonnummer (geografisch, gratis of mobiel), opdrachttype (persoon of toepassing), bel- en sms-mogelijkheden, een netnummer en een aantal telefoonnummers op te geven. De opgegeven hoeveelheid telefoonnummers wordt gedurende 15 minuten gereserveerd. Deze zoekopdracht naar telefoonnummers kan worden geannuleerd of gekocht. Als de zoekopdracht wordt geannuleerd, zijn de telefoonnummers beschikbaar voor anderen. Als de zoekopdracht is aangeschaft, worden de telefoonnummers voor de Azure-resource verkregen.

Telefoonnummers configureren

Telefoonnummers kunnen een combinatie van mogelijkheden hebben. Ze kunnen worden geconfigureerd ter ondersteuning van binnenkomend en/of uitgaand bellen, of niet als u het telefoonnummer niet gebruikt voor bellen. Hetzelfde geldt voor sms-mogelijkheden.

Het is belangrijk om rekening te houden met het toewijzingstype van uw telefoonnummer. Sommige mogelijkheden zijn beperkt tot een bepaald toewijzingstype.

Telefoonnummers bekijken en reserveren

De API's Bladeren en Reserveringen bieden een alternatieve manier om telefoonnummers te verkrijgen via een winkelwagenachtige ervaring. Dit wordt bereikt door de zoekbewerking, die nummers vindt en reserveert met behulp van een enkele LRO, op te splitsen in twee afzonderlijke synchrone stappen, Bladeren en Reserveren.

De bladerbewerking haalt een willekeurige steekproef op van telefoonnummers die beschikbaar zijn voor aankoop voor een bepaald land, met optionele filtercriteria om de resultaten te verfijnen. De geretourneerde telefoonnummers zijn niet gereserveerd voor klanten.

Reserveringen vertegenwoordigen een verzameling telefoonnummers die door een specifieke klant zijn vergrendeld en wachten op aankoop. Ze hebben een vervaltijd van 15 minuten na de laatste wijziging of 2 uur vanaf het moment van aanmaak. Een reservering kan nummers uit verschillende landen bevatten, in tegenstelling tot de zoekfunctie. Klanten kunnen reserveringen aanmaken, ophalen, wijzigen (door nummers toe te voegen en te verwijderen), verwijderen en kopen. Het kopen van een reservering is een LRO.

SIP-routeringsclient

Met de functie directe routering kunt u de door de klant geleverde telefonie-infrastructuur verbinden met Azure Communication Resources. Om de routeringsconfiguratie correct in te stellen, moet de klant de SIP Trunk-configuratie en SIP-routeringsregels voor aanroepen opgeven. SIP-routeringsclient biedt de benodigde interface voor het instellen van deze configuratie.

Wanneer een aanroep wordt gedaan, probeert het systeem het doelnummer te vinden met regex-nummerpatronen van gedefinieerde routes. De eerste route die overeenkomt met het nummer wordt geselecteerd. De volgorde van regex-overeenkomsten is hetzelfde als de volgorde van routes in configuratie, dus de volgorde van routes is van belang. Zodra een route overeenkomt, wordt de aanroep doorgestuurd naar de eerste trunk in de lijst met trunks van de route. Als de trunk niet beschikbaar is, wordt de volgende hoofdstam in de lijst geselecteerd.

Voorbeelden

Authenticatie

Als u een clientobject wilt maken voor toegang tot de Communication Services-API, hebt u een connection string of de endpoint van uw Communication Services-resource en een credentialnodig. De phone numbers-client kan Azure Active Directory-referenties of een API-sleutelreferentie gebruiken om te verifiëren.

U kunt een sleutel en/of verbindingsreeks ophalen uit uw Communication Services-resource in de Azure Portal. U kunt ook het eindpunt voor uw Communication Services-resource vinden in de Azure Portal.

Zodra u een sleutel hebt, kunt u de client verifiëren met een van de volgende methoden:

Een verbindingsreeks gebruiken

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

Een toegangssleutel gebruiken met AzureKeyCredential

Als u een sleutel gebruikt om de client te initialiseren, moet u ook het juiste eindpunt opgeven. U kunt dit eindpunt ophalen uit uw Communication Services-resource in Azure Portal. Zodra u een sleutel en eindpunt hebt, kunt u zich verifiëren met de volgende code:

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

Een Azure Active Directory-referentie gebruiken

Verificatie van verbindingsreeksen wordt in de meeste voorbeelden gebruikt, maar u kunt zich ook verifiëren met Azure Active Directory met behulp van de Azure Identity-bibliotheek. Als u de DefaultAzureCredential- provider wilt gebruiken die hieronder wordt weergegeven, of andere referentieproviders die zijn opgegeven bij de Azure SDK, installeert u het @azure/identity-pakket:

npm install @azure/identity

Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. De LEESMIJ voor @azure/identity biedt meer informatie en voorbeelden om u op weg te helpen.

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

Gebruik

De volgende secties bevatten codefragmenten die betrekking hebben op een aantal algemene taken met behulp van de Azure Communication Services Phone Numbers-client. De scenario's die hier worden behandeld, bestaan uit:

TelefoonnummersClient

SipRouting-client

TelefoonnummersClient

Zoeken naar beschikbare telefoonnummers

Gebruik de methode beginSearchAvailablePhoneNumbers om te zoeken naar telefoonnummers en deze te reserveren. De geretourneerde telefoonnummers zijn 15 minuten gereserveerd en kunnen tijdens deze periode worden aangeschaft door de searchId aan de beginPurchasePhoneNumbers methode op te geven.

beginSearchAvailablePhoneNumbers is een langdurige bewerking en retourneert een 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}`);

Gebruik de beginPurchasePhoneNumbers methode om de telefoonnummers te kopen bij uw zoekopdracht. Aangeschafte telefoonnummers worden toegewezen aan de Communication Services-resource die wordt gebruikt bij het initiëren van de client. De searchId die wordt geretourneerd uit beginSearchAvailablePhoneNumbers is vereist.

beginPurchasePhoneNumbers is een langdurige bewerking en retourneert een 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]}`);

Blader en reserveer beschikbare telefoonnummers

De API Bladeren en Reserveringen gebruiken om een telefoonnummer te reserveren

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

Een gekocht telefoonnummer vrijgeven

Gebruik de methode beginReleasePhoneNumber om een eerder gekocht telefoonnummer vrij te geven. Vrijgegeven telefoonnummers worden niet meer gekoppeld aan de Communication Services-resource en zijn niet beschikbaar voor gebruik met andere bewerkingen (bijvoorbeeld SMS) van de resource. Het telefoonnummer dat wordt vrijgegeven, is vereist.

beginReleasePhoneNumber is een langdurige bewerking en retourneert een 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.");

Mogelijkheden voor telefoonnummers bijwerken

Gebruik de methode beginUpdatePhoneNumberCapabilities om de mogelijkheden van een gekocht telefoonnummer bij te werken. Telefoonnummers kunnen worden geconfigureerd ter ondersteuning van inkomende en/of uitgaande oproepen en sms's, of geen van beide.

beginUpdatePhoneNumberCapabilities is een langdurige bewerking en retourneert een 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}`);

Een gekocht telefoonnummer ophalen

Gebruik de methode getPurchasedPhoneNumber om informatie over een gekocht telefoonnummer op te halen. Deze informatie omvat het type telefoonnummer, de mogelijkheden, de kosten en de aankoopdatum.

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

Aankoop reservering

Als je een bestaande en actieve reservering hebt, koop je de telefoonnummers in die reservering.

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

Aangeschafte telefoonnummers vermelden

Gebruik de methode listPurchasedPhoneNumbers om door alle aangeschafte telefoonnummers te bladeren.

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

SipRouting-client

SIP-trunks en -routes ophalen

Haal de lijst met momenteel geconfigureerde trunks of routes op.

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-trunks en -routes vervangen

Vervang de lijst met momenteel geconfigureerde trunks of routes door nieuwe waarden.

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

Eén trunk ophalen

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

Eén trunk instellen

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

Eén trunk verwijderen

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

Probleemoplossing

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Volgende stappen

Bekijk de voorbeelden map voor gedetailleerde voorbeelden over het gebruik van deze bibliotheek.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.