Share via

Azure Communication Phone Numbers-Clientbibliothek für JavaScript– Version 1.0.0

  • Artikel

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

Erworbene Telefonnummern können je nach Land, Nummerntyp und Zuordnungstyp viele Funktionen aufweisen. Beispiele für Funktionen sind ein- und ausgehende SMS-Nutzung, eingehende und ausgehende PSTN-Nutzung. Telefonnummern können einem Bot auch über eine Webhook-URL zugewiesen werden.

Erste Schritte

Voraussetzungen

Installieren von

npm install @azure/communication-phone-numbers

Browserunterstützung

JavaScript-Paket

Um diese Clientbibliothek im Browser verwenden zu können, müssen Sie zunächst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

Wichtige Begriffe

Das Telefonnummernpaket macht die verfügbar, die PhoneNumbersClient Methoden zum Verwalten von Telefonnummern bereitstellt.

Telefonnummerntypen

Telefonnummern gibt es in zwei Arten; Geografisch und gebührenfrei. Geografische Telefonnummern sind Telefonnummern, die einem Standort zugeordnet sind, dessen Ortsvorwahlen der Ortsvorwahl eines geografischen Standorts zugeordnet sind. Toll-Free Telefonnummern sind keinem Standort zugeordnet. In den USA können beispielsweise gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 enthalten sein.

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

Suchen und Abrufen von Nummern

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

Konfigurieren von Telefonnummern

Telefonnummern können über eine Kombination von Funktionen verfügen. Sie können so konfiguriert werden, dass eingehende und/oder ausgehende Anrufe unterstützt werden, oder keines, wenn Sie die Telefonnummer nicht für Anrufe verwenden. Gleiches gilt für SMS-Funktionen.

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

Beispiele

Authentifizierung

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

Sie können einen Schlüssel und/oder eine Verbindungszeichenfolge aus Ihrer Communication Services-Ressource im Azure-Portal abrufen. 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 sich PhoneNumbersClient 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);

Verwenden eines Zugriffsschlüssels mit AzureKeyCredential

Wenn Sie einen Schlüssel zum Initialisieren des Clients verwenden, müssen Sie auch den entsprechenden Endpunkt angeben. Sie können diesen Endpunkt über Ihre Communication Services-Ressource im Azure-Portal abrufen. Sobald 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);

Verwenden von Azure Active Directory-Anmeldeinformationen

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

npm install @azure/identity

Das @azure/identity Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung dazu verwenden kann. Die INFODATEI 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";

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

Verwendung

Die folgenden Abschnitte enthalten Codeausschnitte, die einige der allgemeinen Aufgaben mit dem client für Azure Communication Services Telefonnummern behandeln. Die szenarien, die hier behandelt werden, bestehen aus:

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 Sie die searchId für die beginPurchasePhoneNumbers -Methode angeben.

beginSearchAvailablePhoneNumbers ist ein vorgang mit langer Ausführungsdauer und gibt einen Poller zurück.

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

Verwenden Sie die beginPurchasePhoneNumbers -Methode, um die Telefonnummern aus Ihrer Suche zu erwerben. Erworbene Telefonnummern werden der Communication Services-Ressource zugewiesen, die beim Initiieren des Clients verwendet wurde. Das searchId von beginSearchAvailablePhoneNumbers zurückgegebene ist erforderlich.

beginPurchasePhoneNumbers ist ein vorgang mit langer Ausführungsdauer und gibt einen Poller zurück.

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

Freigeben einer erworbenen Telefonnummer

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

beginReleasePhoneNumber ist ein vorgang mit langer Ausführungsdauer und gibt einen Poller zurück.

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

Funktionen für Telefonnummern

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 unterstützt werden.

beginUpdatePhoneNumberCapabilities ist ein vorgang mit langer Ausführungsdauer und gibt einen Poller zurück.

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

Abrufen einer erworbenen Telefonnummer

Verwenden Sie die getPurchasedPhoneNumber -Methode, um Informationen zu einer erworbenen Telefonnummer abzurufen. Diese Informationen umfassen den Typ, die Funktionen, die Kosten und das Kaufdatum der Telefonnummer.

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

Auflisten von erworbenen Telefonnummern

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

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

Problembehandlung

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis .

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe