Sdílet prostřednictvím

Klientská knihovna Azure Communication Phone Numbers pro JavaScript – verze 1.5.0

Knihovna telefonních čísel poskytuje možnosti pro správu telefonních čísel.

Zakoupená telefonní čísla můžou obsahovat mnoho funkcí v závislosti na zemi, typu čísla a typu přiřazení. Mezi příklady možností patří příchozí a odchozí využití SMS, příchozí a odchozí využití veřejné telefonní sítě. Telefonní čísla je možné robotovi přiřadit také prostřednictvím adresy URL webhooku.

Začínáme

Požadavky

  • Předplatné Azure.
  • Existující prostředek komunikační služby. Pokud potřebujete prostředek vytvořit, můžete použít webuAzure Portal, Azure PowerShellu nebo Azure CLI.

Instalování

npm install @azure/communication-phone-numbers

Podpora prohlížeče

JavaScriptový balíček

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci sdružování.

Klíčové koncepty

Tato sada SDK poskytuje funkce pro snadnou správu direct offer a direct routing čísel.

Čísla direct offer jsou k dispozici ve třech typech: geografická, Toll-Free a mobilní. Geografické plány a plány mobilních telefonů jsou telefonní plány spojené s umístěním, jejichž směrová čísla jsou spojena s předčíslím zeměpisné oblasti. Toll-Free telefonní tarify jsou telefonní plány, které nejsou přidružené k poloze. Například v USA mohou bezplatná čísla obsahovat směrové číslo oblasti, například 800 nebo 888. Spravují se pomocí PhoneNumbersClient

Funkce direct routing umožňuje připojit stávající telefonní infrastrukturu k ACS. Konfigurace se spravuje pomocí SipRoutingClient, která poskytuje metody pro nastavení kmenů SIP a pravidel hlasového směrování, aby bylo možné správně zpracovat volání pro podsíť telefonie.

Klient telefonních čísel

Typy telefonních čísel

Telefonní čísla se dodávají ve třech typech; Geografické, Toll-Free a mobilní. Toll-Free čísla nejsou spojena s umístěním. Například v USA mohou bezplatná čísla obsahovat směrové číslo oblasti, například 800 nebo 888. Geografická čísla a čísla mobilních telefonů jsou telefonní čísla spojená s určitým místem.

Typy telefonních čísel se stejnou zemí jsou seskupeny do skupiny telefonních tarifů s tímto typem telefonního čísla. Například všechna telefonní čísla Toll-Free v rámci jedné země jsou seskupena do skupiny telefonních tarifů.

Vyhledávání a získávání čísel

Telefonní čísla lze vyhledávat prostřednictvím rozhraní API pro vytváření vyhledávání zadáním typu telefonního čísla (geografické, bezplatné nebo mobilní), typu přiřazení (osoba nebo aplikace), možností volání a SMS, předčíslí oblasti a množství telefonních čísel. Zadané množství telefonních čísel bude rezervováno 15 minut. Toto hledání telefonních čísel je možné zrušit nebo zakoupit. Pokud je vyhledávání zrušeno, telefonní čísla budou dostupná ostatním uživatelům. Pokud je vyhledávání zakoupeno, získáte telefonní čísla pro prostředek Azure.

Konfigurace telefonních čísel

Telefonní čísla můžou mít kombinaci funkcí. Dají se nakonfigurovat tak, aby podporovaly příchozí nebo odchozí volání, nebo ani v případě, že nebudete pro volání používat telefonní číslo. Totéž platí pro možnosti sms.

Je důležité zvážit typ zadání vašeho telefonního čísla. Některé funkce jsou omezené na konkrétní typ přiřazení.

Procházení a rezervace telefonních čísel

Rozhraní API pro procházení a rezervace poskytují alternativní způsob, jak získat telefonní čísla prostřednictvím prostředí podobného nákupnímu košíku. Toho je dosaženo rozdělením vyhledávací operace, která vyhledává a rezervuje čísla pomocí jediného LRO, do dvou samostatných synchronních kroků, Procházet a Rezervovat.

Operace procházení načte náhodný vzorek telefonních čísel, která jsou k dispozici pro nákup pro danou zemi, s volitelnými kritérii filtrování pro zúžení výsledků. Vrácená telefonní čísla nejsou vyhrazena pro žádného zákazníka.

Rezervace představují kolekci telefonních čísel, která jsou uzamčena konkrétním zákazníkem a čekají na zakoupení. Mají dobu vypršení platnosti 15 minut po poslední úpravě nebo 2 hodiny od času vytvoření. Rezervace může obsahovat čísla z různých zemí, na rozdíl od operace Vyhledávání. Zákazníci mohou vytvářet, načítat, upravovat (přidáváním a odebíráním čísel), mazat a nakupovat rezervace. Zakoupením rezervace je LRO.

Klient směrování SIP

Funkce přímého směrování umožňuje propojit telefonní infrastrukturu poskytovanou zákazníkem s komunikačními prostředky Azure. Aby bylo možné správně nastavit konfiguraci směrování, musí zákazník zadat konfiguraci kmene SIP a pravidla směrování SIP pro volání. Klient směrování SIP poskytuje nezbytné rozhraní pro nastavení této konfigurace.

Při volání se systém pokusí shodovat s cílovým číslem s číselnými vzory regulárních čísel definovaných tras. Vybere se první trasa odpovídající číslu. Pořadí porovnávání regulárních výrazů je stejné jako pořadí tras v konfiguraci, a proto záleží na pořadí tras. Po spárování trasy se hovor přesměruje na první kmen v seznamu kmenů trasy. Pokud kufr není k dispozici, vybere se další kmen v seznamu.

Příklady

Autentizace

K vytvoření objektu klienta pro přístup k rozhraní API komunikačních služeb budete potřebovat connection string nebo endpoint prostředku komunikační služby a credential. Klient telefonních čísel může k ověření použít přihlašovací údaje Azure Active Directory nebo přihlašovací údaje klíče rozhraní API.

Klíč nebo připojovací řetězec můžete získat z prostředku komunikační služby na webu azure Portal. Koncový bod prostředku komunikační služby najdete také na webu Azure Portal.

Jakmile budete mít klíč, můžete klienta ověřit pomocí některé z následujících metod:

Použití připojovacího řetězce

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

Použití přístupového klíče s AzureKeyCredential

Pokud k inicializaci klienta použijete klíč, budete také muset zadat příslušný koncový bod. Tento koncový bod můžete získat z prostředku služby Communication Services na webu azure Portal. Jakmile máte klíč a koncový bod, můžete se ověřit pomocí následujícího kódu:

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

Použití přihlašovacích údajů Azure Active Directory

Ve většině příkladů se používá ověřování připojovacího řetězce, ale můžete se také ověřit v Azure Active Directory pomocí knihovny Azure Identity Library. Pokud chcete použít poskytovatele DefaultAzureCredential zobrazené níže nebo jiné zprostředkovatele přihlašovacích údajů poskytnuté sadou Azure SDK, nainstalujte balíček @azure/identity:

npm install @azure/identity

Balíček @azure/identity poskytuje řadu typů přihlašovacích údajů, které může vaše aplikace použít k tomu. Soubor README pro @azure/identity poskytuje další podrobnosti a ukázky, které vám pomůžou začít.

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

Zvyk

Následující části obsahují fragmenty kódu, které pokrývají některé běžné úlohy pomocí klienta telefonních čísel služeb Azure Communication Services. Zde popsané scénáře se skládají z:

Klient PhoneNumbers

Klient SipRoutingu

Klient PhoneNumbers

Vyhledání dostupných telefonních čísel

K vyhledání telefonních čísel a jejich rezervaci použijte metodu beginSearchAvailablePhoneNumbers. Vrácená telefonní čísla jsou vyhrazena po dobu 15 minut a během tohoto období je možné zakoupit poskytnutím searchId metodě beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers je dlouhotrvající operace a vrací poller.

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

Použijte metodu beginPurchasePhoneNumbers k nákupu telefonních čísel z hledání. Zakoupená telefonní čísla budou přiřazena k prostředku komunikační služby použitému při zahájení klienta. Je vyžadován searchId vrácený z beginSearchAvailablePhoneNumbers.

beginPurchasePhoneNumbers je dlouhotrvající operace a vrací poller.

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

Procházení a rezervace dostupných telefonních čísel

Použití rozhraní API pro procházení a rezervace k rezervaci telefonního čísla

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

Vydání zakoupeného telefonního čísla

Použijte metodu beginReleasePhoneNumber k vydání dříve zakoupeného telefonního čísla. Vydaná telefonní čísla již nebudou přidružena k prostředku Komunikační služby a nebudou k dispozici pro použití s jinými operacemi (např. SMS zdroje. Telefonní číslo, které se uvolní, se vyžaduje.

beginReleasePhoneNumber je dlouhotrvající operace a vrací poller.

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

Aktualizace možností telefonního čísla

Pomocí metody beginUpdatePhoneNumberCapabilities aktualizujte možnosti zakoupeného telefonního čísla. Telefonní čísla je možné nakonfigurovat tak, aby podporovala příchozí a odchozí hovory a sms nebo ani jedno.

beginUpdatePhoneNumberCapabilities je dlouhotrvající operace a vrací poller.

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

Získání zakoupeného telefonního čísla

K získání informací o zakoupeném telefonním čísle použijte metodu getPurchasedPhoneNumber. Tyto informace zahrnují typ, možnosti, náklady a datum nákupu telefonního čísla.

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

Rezervace nákupu

Pokud máte existující a aktivní rezervaci, zakupte si telefonní čísla uvedená v této rezervaci.

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

Výpis zakoupených telefonních čísel

Pomocí metody listPurchasedPhoneNumbers můžete procházet všechna zakoupená telefonní čísla.

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

Klient SipRoutingu

Načtení kmenů a tras PROTOKOLU SIP

Získejte seznam aktuálně nakonfigurovaných kmenů nebo tras.

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

Nahrazení kmenů a tras PROTOKOLU SIP

Nahraďte seznam aktuálně nakonfigurovaných kmenů nebo tras novými hodnotami.

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

Načtení jednoho kmene

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

Nastavení jednoho kufru

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

Odstranění jednoho kmene

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

Řešení problémů

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Další kroky

Podrobné příklady použití této knihovny najdete v ukázkách adresáři.

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

  • Last updated on