Freigeben über

Clientbibliothek für Azure Communication Phone Numbers für JavaScript – Version 1.3.0

  • Artikel

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.

Die direct offer Zahlen sind in zwei Arten verfügbar: "Geographic" und "Toll-Free". Geografische Telefonpläne sind Telefonpläne, die einem Standort zugeordnet sind, dessen Ortsvorwahlen der Telefonnummern der Ortsvorwahl eines geografischen Standorts zugeordnet 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 sind in zwei Typen enthalten; Geografischer und gebührenfreier Ort. Geografische Telefonnummern sind Telefonnummern, die einem Standort zugeordnet sind, deren Ortsvorwahl der Ortsvorwahl eines geografischen Standorts zugeordnet ist. Toll-Free Telefonnummern sind keinem Standort zugeordnet. Beispielsweise können in den USA gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 enthalten sein.

Alle geografischen Telefonnummern innerhalb desselben Landes werden in einer Telefonplangruppe mit einem Typ geografischer Telefonnummern gruppiert. Alle Toll-Free Telefonnummern innerhalb desselben Landes sind in einer Telefonplangruppe gruppiert.

Suchen und Abrufen von Zahlen

Telefonnummern können über die Sucherstellungs-API durchsucht werden, indem ein Telefonnummerntyp (geografischer oder gebührenfreier), Zuordnungstyp (Person oder Anwendung), Anruf- und SMS-Funktionen, Eine Ortsvorwahl und Anzahl von Telefonnummern bereitgestellt 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.

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

SipRoutingClient

PhoneNumbersClient

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 beginSearchAvailablePhoneNumbers zurückgegebene searchId 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]}`);

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

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.