Dela via

Klientbibliotek för Azure-kommunikationstelefonnummer för JavaScript – version 1.5.0

Biblioteket med telefonnummer innehåller funktioner för telefonnummeradministration.

Köpta telefonnummer kan ha många funktioner, beroende på land, nummertyp och tilldelningstyp. Exempel på funktioner är SMS-inkommande och utgående användning, PSTN-inkommande och utgående användning. Telefonnummer kan också tilldelas till en robot via en webhook-URL.

Komma igång

Förutsättningar

Installera

npm install @azure/communication-phone-numbers

Stöd för webbläsare

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

Viktiga begrepp

Denna SDK tillhandahåller funktioner för att enkelt hantera direct offer och direct routing tal.

Numren direct offer finns i tre typer: Geografiska, Toll-Free och Mobil. Geografiska abonnemang och mobiltelefonabonnemang är telefonabonnemang som är kopplade till en plats, vars riktnummer för telefonnummer är kopplade till riktnumret för en geografisk plats. Toll-Free telefonabonnemang är telefonplaner som inte är associerade platser. I USA kan till exempel avgiftsfria nummer komma med riktnummer som 800 eller 888. De hanteras med hjälp av PhoneNumbersClient

Med funktionen direct routing kan du ansluta din befintliga telefoniinfrastruktur till ACS. Konfigurationen hanteras med hjälp av SipRoutingClient, som tillhandahåller metoder för att konfigurera SIP-trunkar och röstdirigeringsregler för att hantera samtal för telefoniundernätet korrekt.

Telefonnummerklient

Telefonnummertyper

Telefonnummer finns i tre typer; Geografiskt, Toll-Free och mobilt. Toll-Free nummer är inte kopplade till en plats. I USA kan till exempel avgiftsfria nummer komma med riktnummer som 800 eller 888. Geografiska nummer och mobiltelefonnummer är telefonnummer som är kopplade till en plats.

Telefonnummertyper med samma land grupperas i en telefonabonnemangsgrupp med den telefonnummertypen. Till exempel grupperas alla Toll-Free telefonnummer inom samma land i en telefonabonnemangsgrupp.

Söka efter och hämta tal

Telefonnummer kan sökas via API:et för att skapa sökning genom att ange en telefonnummertyp (geografisk, avgiftsfri eller mobil), tilldelningstyp (person eller program), samtals- och sms-funktioner, ett riktnummer och antal telefonnummer. Den angivna mängden telefonnummer reserveras i 15 minuter. Den här sökningen av telefonnummer kan antingen avbrytas eller köpas. Om sökningen avbryts blir telefonnumren tillgängliga för andra. Om sökningen köps hämtas telefonnumren för Azure-resursen.

Konfigurera telefonnummer

Telefonnummer kan ha en kombination av funktioner. De kan konfigureras för att stödja inkommande och/eller utgående samtal, eller om du inte använder telefonnumret för att ringa. Samma sak gäller för sms-funktioner.

Det är viktigt att tänka på tilldelningstypen för ditt telefonnummer. Vissa funktioner är begränsade till en viss tilldelningstyp.

Bläddra bland och reservera telefonnummer

API:erna för bläddring och reservationer är ett alternativt sätt att skaffa telefonnummer via en kundvagnsliknande upplevelse. Detta uppnås genom att dela upp sökoperationen, som hittar och reserverar nummer med hjälp av en enda LRO, i två separata synkrona steg, Bläddra och Reservation.

Bläddringsåtgärden hämtar ett slumpmässigt urval av telefonnummer som är tillgängliga för köp i ett visst land, med valfria filtreringskriterier för att begränsa resultaten. De returnerade telefonnumren är inte reserverade för någon kund.

Reservationer representerar en samling telefonnummer som är låsta av en viss kund och väntar på köp. De har en förfallotid på 15 minuter efter den senaste ändringen eller 2 timmar från skapandet. En reservation kan innehålla nummer från olika länder, till skillnad från sökfunktionen. Kunder kan skapa, hämta, ändra (genom att lägga till och ta bort nummer), ta bort och köpa reservationer. Att köpa en reservation är en LRO.

SIP-routningsklient

Med direktdirigeringsfunktionen kan du ansluta en telefoniinfrastruktur som tillhandahålls av kunden till Azure Communication Resources. För att kunna konfigurera routningskonfigurationen korrekt måste kunden ange SIP-trunkkonfigurationen och SIP-routningsreglerna för anrop. SIP-routningsklienten tillhandahåller det nödvändiga gränssnittet för att ställa in den här konfigurationen.

När ett anrop görs försöker systemet matcha målnumret med regexnummermönster för definierade vägar. Den första vägen som matchar talet väljs. Ordningen på regexmatchning är densamma som ordningen på vägarna i konfigurationen, därför är ordningen på vägarna viktig. När en väg har matchats dirigeras anropet till den första stammen i vägens stamlista. Om stammen inte är tillgänglig väljs nästa stam i listan.

Exempel

Autentisering

Om du vill skapa ett klientobjekt för åtkomst till Communication Services-API:et behöver du en connection string eller endpoint för din Communication Services-resurs och en credential. Phone Numbers-klienten kan använda antingen Azure Active Directory-autentiseringsuppgifter eller en API-nyckelautentiseringsuppgifter för att autentisera.

Du kan hämta en nyckel och/eller anslutningssträng från din Communication Services-resurs i Azure-portalen. Du kan också hitta slutpunkten för din Communication Services-resurs i Azure Portal.

När du har en nyckel kan du autentisera klienten med någon av följande metoder:

Använda en anslutningssträng

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

Använda en åtkomstnyckel med AzureKeyCredential

Om du använder en nyckel för att initiera klienten måste du också ange rätt slutpunkt. Du kan hämta den här slutpunkten från din Communication Services-resurs i Azure Portal. När du har en nyckel och slutpunkt kan du autentisera med följande kod:

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

Använda en Azure Active Directory-autentiseringsuppgift

Autentisering av anslutningssträngar används i de flesta av exemplen, men du kan också autentisera med Azure Active Directory med hjälp av Azure Identity-biblioteket. Installera -paketet om du vill använda @azure/identity som visas nedan eller andra leverantörer av autentiseringsuppgifter som tillhandahålls med Azure SDK:

npm install @azure/identity

@azure/identity-paketet innehåller en mängd olika typer av autentiseringsuppgifter som programmet kan använda för att göra detta. I README för @azure/identity finns mer information och exempel för att komma igång.

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

Användning

Följande avsnitt innehåller kodfragment som täcker några av de vanliga uppgifterna med hjälp av Azure Communication Services Phone Numbers-klienten. De scenarier som beskrivs här består av:

TelefonnummerKlient

SipRoutingClient (på engelska)

TelefonnummerKlient

Sök efter tillgängliga telefonnummer

Använd metoden beginSearchAvailablePhoneNumbers för att söka efter telefonnummer och reservera dem. De telefonnummer som returneras är reserverade i 15 minuter och kan köpas under den här perioden genom att tillhandahålla searchId till metoden beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers är en tidskrävande åtgärd och returnerar en 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}`);

Använd metoden beginPurchasePhoneNumbers för att köpa telefonnummer från sökningen. Köpta telefonnummer tilldelas till den Communication Services-resurs som används när klienten initieras. Den searchId som returneras från beginSearchAvailablePhoneNumbers krävs.

beginPurchasePhoneNumbers är en tidskrävande åtgärd och returnerar en 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]}`);

Bläddra bland och reservera tillgängliga telefonnummer

Använd API:et för bläddring och reservationer för att reservera ett telefonnummer

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

Släpp ett köpt telefonnummer

Använd metoden beginReleasePhoneNumber för att släppa ett tidigare köpt telefonnummer. Utgivna telefonnummer kommer inte längre att associeras med Communication Services-resursen och kommer inte att vara tillgängliga för användning med andra åtgärder (t.ex. SMS) för resursen. Det telefonnummer som släpps krävs.

beginReleasePhoneNumber är en tidskrävande åtgärd och returnerar en 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.");

Uppdatera funktioner för telefonnummer

Använd metoden beginUpdatePhoneNumberCapabilities för att uppdatera funktionerna i ett köpt telefonnummer. Telefonnummer kan konfigureras för att stödja inkommande och/eller utgående samtal och sms, eller ingetdera.

beginUpdatePhoneNumberCapabilities är en tidskrävande åtgärd och returnerar en 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}`);

Hämta ett köpt telefonnummer

Använd metoden getPurchasedPhoneNumber för att få information om ett köpt telefonnummer. Den här informationen omfattar telefonnumrets typ, funktioner, kostnad och inköpsdatum.

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

Reservation för köp

Om du har en befintlig och aktiv reservation köper du telefonnumren i den reservationen.

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

Lista köpta telefonnummer

Använd metoden listPurchasedPhoneNumbers för att bläddra igenom alla köpta telefonnummer.

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 (på engelska)

Hämta SIP-stammar och vägar

Hämta listan över för närvarande konfigurerade stammar eller vägar.

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

Ersätt SIP-stammar och vägar

Ersätt listan över för närvarande konfigurerade stammar eller vägar med nya värden.

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

Hämta enkel stam

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

Ange enkel stam

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

Ta bort enkel stam

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

Felsökning

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i @azure/logger-paketdokumenten.

Nästa steg

Ta en titt på exempel katalog för detaljerade exempel på hur du använder det här biblioteket.

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

  • Last updated on