Condividi tramite

Libreria client Numeri di telefono di comunicazione di Azure per JavaScript - versione 1.5.0

La libreria dei numeri di telefono offre funzionalità per l'amministrazione dei numeri di telefono.

I numeri di telefono acquistati possono essere dotati di molte funzionalità, a seconda del paese, del tipo di numero e del tipo di assegnazione. Esempi di funzionalità sono l'utilizzo in ingresso e in uscita degli SMS, l'utilizzo in ingresso e in uscita PSTN. I numeri di telefono possono anche essere assegnati a un bot tramite un URL webhook.

Introduttiva

Prerequisiti

  • Una sottoscrizione di Azure .
  • Una risorsa di Servizi di comunicazione esistente. Se è necessario creare la risorsa, è possibile usare il portale di Azure , il Azure PowerShello l'interfaccia della riga di comando di Azure .

Installazione

npm install @azure/communication-phone-numbers

Supporto browser

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

Concetti chiave

Questo SDK offre funzionalità per gestire facilmente direct offer e direct routing numeri.

I direct offer numeri sono di tre tipi: Geographic, Toll-Free e Mobile. I piani geografici e di telefonia mobile sono piani telefonici associati a una località, i cui prefissi dei numeri di telefono sono associati al prefisso di una località geografica. Toll-Free piani telefonici sono piani telefonici non associati. Ad esempio, negli Stati Uniti, i numeri verdi possono venire con codici di area come 800 o 888. Vengono gestiti usando il PhoneNumbersClient

La funzionalità direct routing consente di connettere l'infrastruttura di telefonia esistente a ACS. La configurazione viene gestita usando il SipRoutingClient, che fornisce metodi per configurare trunk SIP e regole di routing vocale, per gestire correttamente le chiamate per la subnet di telefonia.

Client numeri di telefono

Tipi di numeri di telefono

I numeri di telefono sono di tre tipi; Geografico, Toll-Free e mobile. Toll-Free numeri non sono associati a una posizione. Ad esempio, negli Stati Uniti, i numeri verdi possono venire con codici di area come 800 o 888. I numeri di telefono geografici e di cellulare sono numeri di telefono associati a una posizione.

I tipi di numeri di telefono con lo stesso paese vengono raggruppati in un gruppo di piani telefonici con quel tipo di numero di telefono. Ad esempio, tutti i numeri di telefono Toll-Free all'interno dello stesso paese vengono raggruppati in un gruppo di piani telefonici.

Ricerca e acquisizione di numeri

I numeri di telefono possono essere cercati tramite l'API di creazione della ricerca fornendo un tipo di numero di telefono (geografico, numero verde o cellulare), tipo di assegnazione (persona o applicazione), funzionalità di chiamata e sms, un prefisso e la quantità di numeri di telefono. La quantità fornita di numeri di telefono sarà riservata per 15 minuti. Questa ricerca di numeri di telefono può essere annullata o acquistata. Se la ricerca viene annullata, i numeri di telefono diventano disponibili per altri utenti. Se la ricerca viene acquistata, i numeri di telefono vengono acquisiti per la risorsa di Azure.

Configurazione dei numeri di telefono

I numeri di telefono possono avere una combinazione di funzionalità. Possono essere configurati per supportare le chiamate in ingresso e/o in uscita o nessuno dei due se non si userà il numero di telefono per le chiamate. Lo stesso vale per le funzionalità sms.

È importante considerare il tipo di assegnazione del numero di telefono. Alcune funzionalità sono limitate a un particolare tipo di assegnazione.

Navigazione e prenotazione dei numeri di telefono

Le API Sfoglia e Prenotazioni offrono un modo alternativo per acquisire numeri di telefono tramite un'esperienza simile a un carrello della spesa. A tale scopo, l'operazione di ricerca, che consente di trovare e riservare i numeri utilizzando un singolo oggetto di ricerca locale, è suddivisa in due passaggi sincroni separati, Sfoglia e Prenota.

L'operazione di ricerca recupera un campione casuale di numeri di telefono disponibili per l'acquisto per un determinato paese, con criteri di filtro facoltativi per restringere i risultati. I numeri di telefono restituiti non sono riservati a nessun cliente.

Le prenotazioni rappresentano una raccolta di numeri di telefono bloccati da un cliente specifico e in attesa di acquisto. Hanno una scadenza di 15 minuti dopo l'ultima modifica o di 2 ore dalla data di creazione. Una prenotazione può includere numeri di paesi diversi, a differenza dell'operazione di ricerca. I clienti possono creare, recuperare, modificare (aggiungendo e rimuovendo numeri), eliminare e acquistare prenotazioni. L'acquisto di una prenotazione è un LRO.

Client di routing SIP

La funzionalità di routing diretto consente di connettere l'infrastruttura di telefonia fornita dal cliente alle risorse di comunicazione di Azure. Per configurare correttamente la configurazione del routing, il cliente deve fornire la configurazione del trunk SIP e le regole di routing SIP per le chiamate. Il client di routing SIP fornisce l'interfaccia necessaria per impostare questa configurazione.

Quando viene effettuata una chiamata, il sistema tenta di trovare la corrispondenza con il numero di destinazione con i modelli di numero regex delle route definite. Verrà selezionata la prima route che corrisponde al numero. L'ordine di corrispondenza delle espressioni regolari è uguale all'ordine delle route nella configurazione, pertanto l'ordine delle route è importante. Una volta trovata una corrispondenza con una route, la chiamata viene instradata al primo trunk nell'elenco dei trunk della route. Se il trunk non è disponibile, viene selezionato il trunk successivo nell'elenco.

Esempi

Autenticazione

Per creare un oggetto client per accedere all'API di Servizi di comunicazione, è necessario un connection string o la endpoint della risorsa di Servizi di comunicazione e un credential. Il client Numeri di telefono può usare le credenziali di Azure Active Directory o una credenziale della chiave API per l'autenticazione.

È possibile ottenere una chiave e/o una stringa di connessione dalla risorsa servizi di comunicazione nel portale di Azure . È anche possibile trovare l'endpoint per la risorsa servizi di comunicazione nel portale di Azure .

Dopo aver ottenuto una chiave, è possibile autenticare il client con uno dei metodi seguenti:

Uso di una stringa di connessione

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

Uso di una chiave di accesso con AzureKeyCredential

Se si usa una chiave per inizializzare il client, sarà necessario fornire anche l'endpoint appropriato. È possibile ottenere questo endpoint dalla risorsa servizi di comunicazione in portale di Azure. Dopo aver creato una chiave e un endpoint, è possibile eseguire l'autenticazione con il codice seguente:

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

Uso di credenziali di Azure Active Directory

L'autenticazione della stringa di connessione viene usata nella maggior parte degli esempi, ma è anche possibile eseguire l'autenticazione con Azure Active Directory usando libreria di identità di Azure. Per usare il provider DefaultAzureCredential illustrato di seguito o altri provider di credenziali forniti con Azure SDK, installare il pacchetto @azure/identity:

npm install @azure/identity

Il pacchetto @azure/identity offre diversi tipi di credenziali che l'applicazione può usare per eseguire questa operazione. Il file LEGGIMI per @azure/identity fornisce altri dettagli ed esempi per iniziare.

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

Uso

Le sezioni seguenti forniscono frammenti di codice che illustrano alcune delle attività comuni che usano il client numeri di telefono di Servizi di comunicazione di Azure. Gli scenari illustrati di seguito sono costituiti da:

Numeri di telefonoCliente

SipRoutingClient

Numeri di telefonoCliente

Cercare i numeri di telefono disponibili

Usare il metodo beginSearchAvailablePhoneNumbers per cercare i numeri di telefono e riservarli. I numeri di telefono restituiti sono riservati per 15 minuti e possono essere acquistati durante questo periodo fornendo il searchId al metodo di beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers è un'operazione a esecuzione prolungata e restituisce un 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}`);

Usare il metodo beginPurchasePhoneNumbers per acquistare i numeri di telefono dalla ricerca. I numeri di telefono acquistati verranno assegnati alla risorsa servizi di comunicazione usata all'avvio del client. Il searchId restituito dalla beginSearchAvailablePhoneNumbers è obbligatorio.

beginPurchasePhoneNumbers è un'operazione a esecuzione prolungata e restituisce un 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]}`);

Sfoglia e prenota i numeri di telefono disponibili

Utilizzare l'API Sfoglia e prenotazioni per prenotare un numero di telefono

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

Rilasciare un numero di telefono acquistato

Usare il metodo beginReleasePhoneNumber per rilasciare un numero di telefono acquistato in precedenza. I numeri di telefono rilasciati non saranno più associati alla risorsa servizi di comunicazione e non saranno disponibili per l'uso con altre operazioni (ad esempio. SMS) della risorsa. Il numero di telefono rilasciato è obbligatorio.

beginReleasePhoneNumber è un'operazione a esecuzione prolungata e restituisce un 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.");

Aggiornare le funzionalità dei numeri di telefono

Usare il metodo beginUpdatePhoneNumberCapabilities per aggiornare le funzionalità di un numero di telefono acquistato. I numeri di telefono possono essere configurati per supportare chiamate in ingresso e/o in uscita e sms o nessuno dei due.

beginUpdatePhoneNumberCapabilities è un'operazione a esecuzione prolungata e restituisce un 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}`);

Ottenere un numero di telefono acquistato

Utilizzare il metodo getPurchasedPhoneNumber per ottenere informazioni su un numero di telefono acquistato. Queste informazioni includono il tipo, le funzionalità, il costo e la data di acquisto del numero di telefono.

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

Prenotazione dell'acquisto

Data una prenotazione esistente e attiva, acquista i numeri di telefono in tale prenotazione.

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

Elencare i numeri di telefono acquistati

Utilizzare il metodo listPurchasedPhoneNumbers per scorrere tutti i numeri di telefono acquistati.

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

Recuperare trunk e route SIP

Ottenere l'elenco di trunk o route attualmente configurati.

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

Sostituire trunk e route SIP

Sostituire l'elenco di trunk o route attualmente configurati con nuovi valori.

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

Recuperare un singolo trunk

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

Impostare un singolo trunk

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

Eliminare un singolo trunk

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

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere gli esempi di directory.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

  • Last updated on