Condividi tramite

Libreria client di Amministrazione delle comunicazioni di Azure per JavaScript - versione 1.0.0-beta.3

  • Articolo

La libreria di amministrazione viene usata per la gestione di utenti e token per Servizi di comunicazione di Azure. Questa libreria offre anche funzionalità per l'amministrazione dei numeri di telefono.

I numeri di telefono acquisiti possono essere dotati di molte funzionalità, a seconda del paese, del tipo di numero e del piano telefonico. 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.

Introduzione

Prerequisiti

Installazione

npm install @azure/communication-administration

Concetti chiave

Client

Il pacchetto di amministrazione espone due client. fornisce CommunicationIdentityClient metodi per gestire gli utenti e i relativi token. Fornisce PhoneNumberAdministrationClient metodi per gestire piani telefonici e numeri.

Panoramica dei piani telefonici

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

Tutti i piani telefonici geografici all'interno dello stesso paese sono raggruppati in un gruppo di piani telefonici con un tipo di numero di telefono geografico. Tutti i piani telefonici Toll-Free nello stesso paese sono raggruppati in un gruppo di piani telefonici.

Ricerca e acquisizione di numeri

I numeri di telefono possono essere cercati nell'API di creazione della ricerca fornendo un ID piano telefonico, un codice di area e una quantità di numeri di telefono. La quantità fornita di numeri di telefono verrà riservata per dieci minuti. Questa ricerca di numeri di telefono può essere annullata o acquistata. Se la ricerca viene annullata, i numeri di telefono diventeranno disponibili per altri utenti. Se la ricerca viene acquistata, i numeri di telefono vengono acquisiti per le risorse di Azure.

Configurazione e assegnazione di numeri

I numeri di telefono possono essere assegnati a un URL di callback tramite l'API configura numero. Come parte della configurazione, è necessario un numero di telefono acquisito, un URL di callback e un ID applicazione.

Esempio

Authentication

È possibile ottenere una chiave e/o una stringa di connessione dalla risorsa di Servizi di comunicazione nel portale di Azure. Dopo aver ottenuto una chiave, è possibile autenticare CommunicationIdentityClient e PhoneNumberAdministrationClient con uno dei metodi seguenti:

Creare KeyCredential con AzureKeyCredential prima di inizializzare il client

import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-administration";

const credential = new AzureKeyCredential(KEY);
const client = new CommunicationIdentityClient(HOST, credential);

Uso di una stringa di connessione

import { PhoneNumberAdministrationClient } from "@azure/communication-administration";

const connectionString = `endpoint=HOST;accessKey=KEY`;
const client = new CommunicationIdentityClient(connectionString);

Se si usa una chiave per inizializzare il client, sarà necessario specificare anche l'endpoint appropriato. È possibile ottenere questo endpoint dalla risorsa di Servizi di comunicazione nel portale di Azure.

Utilizzo

CommunicationIdentityClient

Creazione di un'istanza di CommunicationIdentityClient

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Creazione di un nuovo utente

Usare il createUser metodo per creare un nuovo utente.

const user = await client.createUser();

Creazione e aggiornamento di un token utente

Usare il issueToken metodo per rilasciare o aggiornare un token per un utente esistente. Il metodo accetta anche un elenco di ambiti del token di comunicazione. Le opzioni di ambito includono:

  • chat (Chat)
  • pstn (Rete telefonica commutata pubblica)
  • voip (Voice over IP)
let { token } = await client.issueToken(user, ["chat"]);

Per aggiornare il token utente, emettere un altro token con lo stesso utente.

{ token } = await client.issueToken(user, ["chat"]);

Revoca dei token per un utente

Usare il revokeTokens metodo per revocare tutti i token emessi di un utente.

await client.revokeTokens(user);

revokeTokens accetta un secondo argomento facoltativo, tokensValidFrom. Se questa data viene specificata, revokeTokens revoca tutti i token rilasciati prima. In caso contrario, tutti i token verranno revocati.

Eliminazione di un utente

Usare il deleteUser metodo per eliminare un utente.

await client.deleteUser(user);

PhoneNumberAdministrationClient

Creazione di un'istanza di PhoneNumberAdministrationClient

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Ottenere paesi

Usare il listSupportedCountries metodo per ottenere un elenco dei paesi supportati.

const countries = await client.listSupportedCountries();

for await (const country of countries) {
  console.log(`Country code: ${country.countryCode}`);
  console.log(`Country name: ${country.localizedName}`);
}

Recupero dei gruppi di piani telefonici

I gruppi di piani telefonici sono disponibili in due tipi, Geografico e Gratuito. Usare il listPhonePlanGroups metodo per ottenerli.

const countryCode = "US";
const phonePlanGroups = await client.listPhonePlanGroups(countryCode);

for await (const phonePlanGroup of phonePlanGroups) {
  console.log(`Phone plan group id: ${phonePlanGroup.phonePlanGroupId}`);
}

Recupero delle opzioni di posizione

Per i piani telefonici geografici, è possibile eseguire una query sulle località geografiche disponibili. Le opzioni di località sono strutturate come la gerarchia geografica di un paese. Ad esempio, gli Stati Uniti hanno stati e all'interno di ogni stato sono città.

Usare il getPhonePlanLocationOptions metodo per ottenere le opzioni per una posizione.

const { locationOptions } = await client.getPhonePlanLocationOptions({
  countryCode: "US",
  phonePlanGroupId: "phonePlanGroupId",
  phonePlanId: "phonePlanId"
});

console.log(`Got location options for: ${locationOptions.labelId}`);

Recupero dei codici di area

Il recupero dei codici di area per i piani telefonici geografici richiederà il set di query per le opzioni di posizione. È necessario includere la catena di posizioni geografiche che attraversano l'oggetto opzioni di posizione restituito da getPhonePlanLocationOptions.

Usare il getAreaCodes metodo per ottenere i codici di area per i piani telefonici geografici.

const { primaryAreaCodes } = await client.getAreaCodes({
  locationType: "selection",
  countryCode: "US",
  phonePlanId: "phonePlanId",
  locationOptionsQueries
});

Prenotazione dei numeri di telefono per l'acquisto

Usare il beginReservePhoneNumbers metodo per cercare i numeri di telefono e prenotarli. L'operazione può richiedere molto tempo.

const reservePoller = await client.beginReservePhoneNumbers({
    name: "Phone number search 800",
    description: "Search for 800 phone numbers"
    phonePlanIds: ["phone-plan-id-1"],
    areaCode: "800",
    quantity: 3
});

Per ottenere i risultati della prenotazione, usare il metodo nel pollUntilDone poller creato.

const phoneNumberReservation = await reservePoller.pollUntilDone();

È possibile annullare il polling e la prenotazione chiamando il cancelOperation metodo sul poller creato.

await reservePoller.cancelOperation();

Acquisto di numeri di telefono da una prenotazione

Usare il beginPurchasePhoneNumbers metodo per acquistare i numeri di telefono dalla prenotazione. L'oggetto reservationId restituito da beginReservePhoneNumbers è obbligatorio. beginPurchasePhoneNumbers è anche un'operazione a esecuzione prolungata.

const { reservationId } = phoneNumberReservation;
const purchasePoller = await client.beginPurchasePhoneNumbers(reservationId);

Per ottenere i risultati dell'acquisto, usare il metodo nel pollUntilDone poller di acquisto creato.

const results = await purchasePoller.pollUntilDone();

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.

Impression