Libreria client numeri di telefono di Comunicazione di Azure per JavaScript - versione 1.0.0

La libreria numeri di telefono offre funzionalità per l'amministrazione del numero 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 di SMS, l'utilizzo in ingresso e in uscita di PSTN. I numeri di telefono possono anche essere assegnati a un bot tramite un URL webhook.

Introduzione

Prerequisiti

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

Installazione

npm install @azure/communication-phone-numbers

Supporto browser

JavaScript Bundle

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

Concetti chiave

Il pacchetto numeri di telefono espone i PhoneNumbersClient metodi che forniscono metodi per gestire i numeri di telefono.

Tipo di numero di telefono

I numeri di telefono sono disponibili in due tipi; Geografico e gratuito. I numeri di telefono geografici sono numeri di telefono associati a una posizione, i cui codici di area sono associati al codice di area di una posizione geografica. Toll-Free numeri di telefono non sono associati a una posizione. Ad esempio, negli Stati Uniti, i numeri verdi possono venire con codici di area, ad esempio 800 o 888.

Tutti i numeri di telefono geografici all'interno dello stesso paese vengono raggruppati in un gruppo di piani telefonici con un tipo di numero di telefono geografico. Tutti i numeri di telefono Toll-Free nello 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 o verde), tipo di assegnazione (persona o applicazione), funzionalità di chiamata e sms, codice di area e 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 saranno 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 chiamate in ingresso e/o in uscita o nessuno dei due se non si userà il numero di telefono per la chiamata. Lo stesso vale per le funzionalità sms.

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

Esempio

Authentication

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

È possibile ottenere una stringa di connessione e/o chiave 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 avere una chiave, è possibile eseguire l'autenticazione PhoneNumbersClient 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);

Uso di una chiave di accesso con AzureKeyCredential

Se si usa una chiave per inizializzare il client, è necessario specificare anche l'endpoint appropriato. È possibile ottenere questo endpoint dalla risorsa servizi di comunicazione nel portale di Azure. Dopo avere 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);

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 la libreria di identità di Azure. Per usare il provider DefaultAzureCredential illustrato di seguito o altri provider di credenziali forniti con Azure SDK, installare il @azure/identity pacchetto:

npm install @azure/identity

Il @azure/identity pacchetto offre un'ampia gamma di tipi di credenziali che l'applicazione può usare per eseguire questa operazione. ReadME per @azure/identity fornisce altri dettagli e esempi per iniziare.

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

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

Utilizzo

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

• Cercare numeri di telefono disponibili
• Acquistare numeri di telefono da una ricerca
• Rilasciare un numero di telefono acquistato
• Aggiornare le funzionalità del numero di telefono
• Ottenere un numero di telefono acquistato
• Elencare i numeri di telefono acquistati

Cercare numeri di telefono disponibili

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

beginSearchAvailablePhoneNumbers è un'operazione a esecuzione prolungata e restituisce un poller.

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const searchRequest = {
    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 = searchPoller.pollUntilDone();
  console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
  console.log(`searchId: ${searchResults.searchId}`);
}

main();

Acquistare numeri di telefono da una ricerca

Usare il beginPurchasePhoneNumbers metodo per acquistare i numeri di telefono dalla ricerca. I numeri di telefono acquistati verranno assegnati alla risorsa Servizi di comunicazione usata durante l'avvio del client. L'oggetto searchId restituito da beginSearchAvailablePhoneNumbers è obbligatorio.

beginPurchasePhoneNumbers è un'operazione a esecuzione prolungata e restituisce un poller.

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const searchRequest = {
    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 } = searchPoller.pollUntilDone();

  const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

  // Purchase is underway.
  await purchasePoller.pollUntilDone();
  console.log(`Successfully purchased ${phoneNumbers[0]}`);
}

main();

Rilasciare un numero di telefono acquistato

Usare il beginReleasePhoneNumber metodo 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 { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const phoneNumberToRelease = "<phone-number-to-release>";

  const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

  // Release is underway.
  await releasePoller.pollUntilDone();
  console.log("Successfully release phone number.");
}

main();

Aggiornare le funzionalità del numero di telefono

Usare il beginUpdatePhoneNumberCapabilities metodo 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 { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const phoneNumberToUpdate = "<phone-number-to-update>";

  // This will update phone number to send and receive sms, but only send calls.
  const updateRequest = {
    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}`);
}

main();

Ottenere un numero di telefono acquistato

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

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async main function() {
  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}`);
}

main();

Elencare i numeri di telefono acquistati

Usare il listPurchasedPhoneNumbers metodo per paginare tutti i numeri di telefono acquistati.

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async main function() {
  const phoneNumbers = await 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}`);
  }
}

main();

Risoluzione dei problemi

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere la directory degli esempi .

Contributo

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

Progetti correlati

• Microsoft Azure SDK per Javascript