Freigeben über

Clientbibliothek für Azure Communication-Telefonnummern für JavaScript – Version 1.5.0

Die Telefonnummernbibliothek bietet Funktionen für die Verwaltung von Telefonnummern.

Gekaufte Telefonnummern können je nach Land, Nummerntyp und Zuordnungstyp viele Funktionen enthalten. Beispiele für Funktionen sind die EINGEHENDE und ausgehende Verwendung von SMS, PSTN-Eingehender und ausgehender Nutzung. Telefonnummern können einem Bot auch über eine Webhook-URL zugewiesen werden.

Erste Schritte

Voraussetzungen

Installation

npm install @azure/communication-phone-numbers

Browserunterstützung

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

Schlüsselkonzepte

Dieses SDK bietet Funktionen zum einfachen Verwalten von direct offer und direct routing Nummern.

Es gibt drei Arten von Zahlen direct offer : Geografisch, Toll-Free und Mobil. Geografische und Mobilfunktarife sind Telefonpläne, die mit einem Standort verknüpft sind, dessen Vorwahlen mit der Vorwahl eines geografischen Standorts verknüpft sind. Toll-Free Telefonpläne sind Telefonpläne, die keinem Standort zugeordnet sind. Beispielsweise können in den USA gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 enthalten sein. Sie werden mithilfe der PhoneNumbersClient verwaltet.

Mit der direct routing-Funktion können Sie Ihre vorhandene Telefonieinfrastruktur mit ACS verbinden. Die Konfiguration wird mithilfe der SipRoutingClientverwaltet, die Methoden zum Einrichten von SIP-Trunks und VoIP-Routingregeln bereitstellt, um Anrufe für Ihr Telefonie-Subnetz ordnungsgemäß zu verarbeiten.

Telefonnummernclient

Telefonnummerntypen

Telefonnummern gibt es in drei Arten; Geografisch, Toll-Free und mobil. Toll-Free Nummern sind nicht mit einem Standort verknüpft. Beispielsweise können in den USA gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 enthalten sein. Geografische und Mobiltelefonnummern sind Telefonnummern, die mit einem Standort verknüpft sind.

Rufnummerntypen mit demselben Land werden in einer Tarifgruppe mit diesem Rufnummerntyp gruppiert. Zum Beispiel werden alle Toll-Free Telefonnummern innerhalb desselben Landes in einer Telefontarifgruppe gruppiert.

Suchen und Abrufen von Zahlen

Telefonnummern können über die Sucherstellungs-API gesucht werden, indem ein Telefonnummerntyp (geografisch, gebührenfrei oder mobil), ein Zuweisungstyp (Person oder Anwendung), Anruf- und SMS-Funktionen, eine Ortsvorwahl und die Anzahl der Telefonnummern angegeben werden. Die angegebene Anzahl von Telefonnummern wird für 15 Minuten reserviert. Diese Suche nach Telefonnummern kann entweder storniert oder gekauft werden. Wenn die Suche abgebrochen wird, werden die Telefonnummern für andere Personen verfügbar. Wenn die Suche gekauft wird, werden die Telefonnummern für die Azure-Ressource erworben.

Konfigurieren von Telefonnummern

Telefonnummern können eine Kombination aus Funktionen aufweisen. Sie können so konfiguriert werden, dass eingehende und/oder ausgehende Anrufe unterstützt werden, oder sie können auch nicht konfiguriert werden, wenn Sie die Telefonnummer für Anrufe nicht verwenden. Das gleiche gilt für sms-Funktionen.

Es ist wichtig, den Zuweisungstyp Ihrer Telefonnummer zu berücksichtigen. Einige Funktionen sind auf einen bestimmten Zuordnungstyp beschränkt.

Durchsuchen und Reservieren von Telefonnummern

Die Durchsuchen- und Reservierungs-APIs bieten eine alternative Möglichkeit, Telefonnummern über eine Einkaufswagen-ähnliche Erfahrung abzurufen. Dies wird erreicht, indem der Suchvorgang, bei dem Nummern mithilfe eines einzelnen LRO gesucht und reserviert werden, in zwei separate synchrone Schritte aufgeteilt wird: Durchsuchen und Reservieren.

Der Browse-Vorgang ruft eine zufällige Stichprobe von Telefonnummern ab, die für ein bestimmtes Land zum Kauf verfügbar sind, mit optionalen Filterkriterien, um die Ergebnisse einzugrenzen. Die zurückgegebenen Telefonnummern sind keinem Kunden vorbehalten.

Reservierungen stellen eine Sammlung von Telefonnummern dar, die von einem bestimmten Kunden gesperrt wurden und auf den Kauf warten. Sie haben eine Ablaufzeit von 15 Minuten nach der letzten Änderung oder 2 Stunden ab der Erstellungszeit. Eine Reservierung kann im Gegensatz zum Suchvorgang Nummern aus verschiedenen Ländern enthalten. Kunden können Reservierungen erstellen, abrufen, ändern (durch Hinzufügen und Entfernen von Nummern), löschen und kaufen. Der Kauf einer Reservierung ist eine LRO.

SIP-Routingclient

Die Direct Routing-Funktion ermöglicht das Verbinden der vom Kunden bereitgestellten Telefonieinfrastruktur mit Azure Communication Resources. Um die Routingkonfiguration ordnungsgemäß einzurichten, muss der Kunde die SIP-Trunkkonfiguration und SIP-Routingregeln für Anrufe bereitstellen. Der SIP-Routingclient stellt die erforderliche Schnittstelle zum Festlegen dieser Konfiguration bereit.

Wenn ein Anruf erfolgt, versucht das System, die Zielnummer mit den Regex-Nummernmustern definierter Routen abzugleichen. Die erste Route, die mit der Nummer übereinstimmt, wird ausgewählt. Die Reihenfolge des Regex-Abgleichs entspricht der Reihenfolge der Routen in der Konfiguration, daher ist die Reihenfolge der Routen wichtig. Sobald eine Route übereinstimmt, wird der Anruf an den ersten Trunk in der Trunksliste der Route weitergeleitet. Wenn der Trunk nicht verfügbar ist, wird der nächste Trunk in der Liste ausgewählt.

Beispiele

Authentifizierung

Um ein Clientobjekt für den Zugriff auf die Kommunikationsdienste-API zu erstellen, benötigen Sie eine connection string oder die endpoint Ihrer Kommunikationsdienste-Ressource und eine credential. Der Client für Telefonnummern kann entweder Azure Active Directory-Anmeldeinformationen oder API-Schlüsselanmeldeinformationen zur Authentifizierung verwenden.

Sie können eine Schlüssel- und/oder Verbindungszeichenfolge aus Ihrer Kommunikationsdienste-Ressource im Azure Portalabrufen. Sie finden den Endpunkt für Ihre Communication Services-Ressource auch im Azure Portal.

Sobald Sie über einen Schlüssel verfügen, können Sie den Client mit einer der folgenden Methoden authentifizieren:

Verwenden einer Verbindungszeichenfolge

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

Verwenden einer Zugriffstaste mit AzureKeyCredential

Wenn Sie einen Schlüssel zum Initialisieren des Clients verwenden, müssen Sie auch den entsprechenden Endpunkt bereitstellen. Sie können diesen Endpunkt aus Ihrer Kommunikationsdienste-Ressource in Azure Portalabrufen. Nachdem Sie über einen Schlüssel und endpunkt verfügen, können Sie sich mit dem folgenden Code authentifizieren:

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

Verwenden von Azure Active Directory-Anmeldeinformationen

Die Verbindungszeichenfolgenauthentifizierung wird in den meisten Beispielen verwendet, Sie können sich aber auch mit Azure Active Directory mithilfe der Azure Identity-Bibliothekauthentifizieren. Um den unten gezeigten DefaultAzureCredential Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie bitte das @azure/identity Paket:

npm install @azure/identity

Das @azure/identity-Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung verwenden kann, um dies zu tun. Die README für @azure/identity enthält weitere Details und Beispiele für die ersten Schritte.

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

Verwendung

In den folgenden Abschnitten werden Codeausschnitte bereitgestellt, die einige der allgemeinen Aufgaben mithilfe des Azure Communication Services Phone Numbers-Clients abdecken. Die hier behandelten Szenarien bestehen aus:

PhoneNumbersClient (Englisch)

SipRoutingClient

PhoneNumbersClient (Englisch)

Suchen nach verfügbaren Telefonnummern

Verwenden Sie die beginSearchAvailablePhoneNumbers-Methode, um nach Telefonnummern zu suchen und diese zu reservieren. Die zurückgegebenen Telefonnummern sind für 15 Minuten reserviert und können während dieses Zeitraums erworben werden, indem die searchId der beginPurchasePhoneNumbers Methode bereitgestellt wird.

beginSearchAvailablePhoneNumbers ist ein lang ausgeführter Vorgang und gibt einen Poller zurück.

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

Verwenden Sie die beginPurchasePhoneNumbers Methode, um die Telefonnummern aus Ihrer Suche zu erwerben. Gekaufte Telefonnummern werden der Kommunikationsdiensteressource zugewiesen, die beim Initiieren des Clients verwendet wird. Die von searchId zurückgegebene beginSearchAvailablePhoneNumbers ist erforderlich.

beginPurchasePhoneNumbers ist ein lang ausgeführter Vorgang und gibt einen Poller zurück.

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

Verfügbare Telefonnummern durchsuchen und reservieren

Verwenden Sie die API zum Durchsuchen und Reservieren, um eine Telefonnummer zu reservieren

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

Freigeben einer erworbenen Telefonnummer

Verwenden Sie die beginReleasePhoneNumber Methode, um eine zuvor erworbene Telefonnummer freizugeben. Freigegebene Telefonnummern werden nicht mehr der Kommunikationsdiensteressource zugeordnet und stehen nicht zur Verwendung mit anderen Vorgängen zur Verfügung (z. B. SMS) der Ressource. Die freigegebene Telefonnummer ist erforderlich.

beginReleasePhoneNumber ist ein lang ausgeführter Vorgang und gibt einen Poller zurück.

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

Aktualisieren von Telefonnummernfunktionen

Verwenden Sie die beginUpdatePhoneNumberCapabilities Methode, um die Funktionen einer erworbenen Telefonnummer zu aktualisieren. Telefonnummern können so konfiguriert werden, dass eingehende und/oder ausgehende Anrufe und SMS oder keines davon unterstützt wird.

beginUpdatePhoneNumberCapabilities ist ein lang ausgeführter Vorgang und gibt einen Poller zurück.

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

Erhalten einer gekauften Telefonnummer

Verwenden Sie die getPurchasedPhoneNumber Methode, um Informationen zu einer gekauften Telefonnummer abzurufen. Diese Informationen umfassen den Typ, die Funktionen, die Kosten und das Kaufdatum der 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 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}`);

Reservierung kaufen

Wenn eine Reservierung vorhanden und aktiv ist, erwerben Sie die Telefonnummern in dieser Reservierung.

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

Auflisten gekaufter Telefonnummern

Verwenden Sie die listPurchasedPhoneNumbers Methode, um alle gekauften Telefonnummern zu durchlaufen.

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

Abrufen von SIP-Trunks und Routen

Dient zum Abrufen der Liste der aktuell konfigurierten Trunks oder Routen.

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

Ersetzen von SIP-Trunks und Routen

Ersetzen Sie die Liste der aktuell konfigurierten Trunks oder Routen durch neue Werte.

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

Abrufen eines einzelnen Trunks

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

Festlegen eines einzelnen Trunks

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

Löschen eines einzelnen Trunks

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

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie in den Beispielen Verzeichnis.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

  • Last updated on