Megosztás a következőn keresztül:

Azure Communication Phone Numbers JavaScript-ügyféloldali kódtár – 1.5.0-s verzió

A telefonszámtár lehetővé teszi a telefonszámok felügyeletét.

A megvásárolt telefonszámok számos funkcióval rendelkezhetnek az országtól, a szám típusától és a hozzárendelés típusától függően. Ilyen például az SMS bejövő és kimenő használata, a PSTN bejövő és kimenő használata. A telefonszámok webhook URL-címen keresztül is hozzárendelhetők a robothoz.

Kezdetekhez

Előfeltételek

Telepítése

npm install @azure/communication-phone-numbers

Böngészőtámogatás

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, először egy kötegelőt kell használnia. Ennek módjáról további információt a csomagküldő dokumentációbantalál.

Főbb fogalmak

Ez az SDK funkcióval egyszerűen kezelheti direct offer és direct routing számokat.

A direct offer számok háromféle típusúak: földrajzi, Toll-Free és mobil. A földrajzi és mobiltelefon-előfizetések olyan helyhez társított telefoncsomagok, amelyek telefonszámainak körzetszáma egy földrajzi hely körzetszámához van társítva. Toll-Free telefoncsomagok nem társított telefoncsomagok. Az USA-ban például az ingyenes számokhoz olyan körzetkódok is lehetnek, mint a 800 vagy a 888. Kezelésük a PhoneNumbersClient

A direct routing funkció lehetővé teszi a meglévő telefonos infrastruktúra csatlakoztatását az ACS-hez. A konfiguráció kezelése a SipRoutingClienthasználatával történik, amely metódusokat biztosít a SIP-csomagok és a hangalapú útválasztási szabályok beállításához a telefonos alhálózat hívásainak megfelelő kezeléséhez.

Telefonszám-ügyfél

Telefonszámtípusok

A telefonszámok háromféle típusúak; Földrajzi, Toll-Free és mobil. Toll-Free számok nem kapcsolódnak helyhez. Az USA-ban például az ingyenes számokhoz olyan körzetkódok is lehetnek, mint a 800 vagy a 888. A földrajzi és a mobiltelefonszámok egy helyhez társított telefonszámok.

Az azonos országhoz tartozó telefonszámtípusok az adott telefonszámtípussal rendelkező telefoncsomag-csoportba vannak csoportosítva. Például az ugyanazon országon belüli összes Toll-Free telefonszám egy telefoncsomag-csoportba van csoportosítva.

Számok keresése és beszerzése

A telefonszámok a kereséskészítő API-n keresztül kereshetők telefonszámtípus (földrajzi, ingyenes vagy mobil), hozzárendelés típusa (személy vagy alkalmazás), hívási és SMS-képességek, körzetszám és telefonszámok mennyiségének megadásával. A megadott telefonszámok mennyisége 15 percig lesz fenntartva. A telefonszámok keresése megszakítható vagy megvásárolható. Ha a keresés megszakad, a telefonszámok elérhetővé válnak mások számára. Ha a keresés meg van vásárolva, akkor a telefonszámok az Azure-erőforráshoz lesznek beolvasva.

Telefonszámok konfigurálása

A telefonszámok a képességek kombinációjával is rendelkezhetnek. Konfigurálhatók úgy, hogy támogassák a bejövő és/vagy kimenő hívásokat, vagy akkor sem, ha nem használja a telefonszámot a híváshoz. Ugyanez vonatkozik az SMS képességeire is.

Fontos figyelembe venni a telefonszám hozzárendelési típusát. Egyes képességek egy adott hozzárendelési típusra korlátozódnak.

Telefonszámok böngészése és lefoglalása

A Tallózás és a Foglalások API-k alternatív módot kínálnak a telefonszámok bevásárlókosár-szerű élményen keresztüli beszerzésére. Ez úgy érhető el, hogy a keresési műveletet, amely egyetlen LRO segítségével keresi és foglalja le a számokat, két különálló szinkron lépésre osztja: Tallózás és Foglalás.

A tallózási művelet egy adott országban megvásárolható telefonszámok véletlenszerű mintáját kéri le, opcionális szűrési feltételekkel az eredmények szűkítéséhez. A visszaküldött telefonszámok nincsenek fenntartva egyetlen ügyfél számára sem.

A foglalások olyan telefonszámok gyűjteményét jelentik, amelyeket egy adott ügyfél zárolt, és amelyek vásárlásra várnak. Lejárati idejük 15 perc az utolsó módosítás után vagy 2 óra a létrehozás időpontjától számítva. A foglalás különböző országokból származó számokat tartalmazhat, ellentétben a keresési művelettel. Az ügyfelek foglalásokat hozhatnak létre, kérhetnek le, módosíthatnak (számok hozzáadásával és eltávolításával), törölhetnek és vásárolhatnak. A foglalás megvásárlása LRO.

SIP-útválasztási ügyfél

A közvetlen útválasztási funkció lehetővé teszi az ügyfél által biztosított telefonos infrastruktúra azure-beli kommunikációs erőforrásokhoz való csatlakoztatását. Az útválasztási konfiguráció megfelelő beállításához az ügyfélnek meg kell adnia a SIP-csomagtartó konfigurációját és az SIP útválasztási szabályait a hívásokhoz. A SIP-útválasztási ügyfél biztosítja a konfiguráció beállításához szükséges felületet.

Hívás esetén a rendszer megpróbál megegyezni a célszámmal a megadott útvonalak regex számmintáival. A program kiválasztja az első útvonalat, amely megfelel a számnak. A regex-egyeztetés sorrendje megegyezik a konfigurációban lévő útvonalak sorrendjének sorrendjében, ezért az útvonalak sorrendje számít. Az útvonal egyeztetése után a rendszer átirányítja a hívást az útvonal törzslistájában szereplő első csomagtartóra. Ha a csomagtartó nem érhető el, a lista következő csomagtartója lesz kiválasztva.

Példák

Hitelesítés

Ahhoz, hogy létrehozhasson egy ügyfélobjektumot a Communication Services API eléréséhez, szüksége lesz egy connection string vagy a Communication Services-erőforrás endpoint és egy credential. A Telefonszámok ügyfél az Azure Active Directory hitelesítő adatait vagy egy API-kulcs hitelesítő adatait használhatja a hitelesítéshez.

Kulcs és/vagy kapcsolati sztring lekérése a Communication Services-erőforrásból az Azure Portal. A Communication Services-erőforrás végpontját az Azure Portal is megtalálhatja.

Miután rendelkezik egy kulccsal, a következő módszerek bármelyikével hitelesítheti az ügyfelet:

Kapcsolati sztring használata

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

Hozzáférési kulcs használata AzureKeyCredential

Ha egy kulccsal inicializálja az ügyfelet, a megfelelő végpontot is meg kell adnia. Ezt a végpontot a Communication Services-erőforrásból szerezheti be Azure Portal. Miután rendelkezik egy kulccsal és végponttal, a következő kóddal hitelesítheti magát:

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

Azure Active Directory hitelesítő adatok használata

A legtöbb példában kapcsolati sztring-hitelesítést használnak, de az Azure Active Directoryval is végezhet hitelesítést az Azure Identity Libraryhasználatával. Az alább látható DefaultAzureCredential szolgáltató vagy az Azure SDK-hoz biztosított egyéb hitelesítő adatok szolgáltatójának használatához telepítse a @azure/identity csomagot:

npm install @azure/identity

A @azure/identity csomag számos hitelesítő adattípust biztosít, amelyeket az alkalmazás használhat erre. A @azure/identity README további részleteket és mintákat tartalmaz az első lépésekhez.

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

Használat

A következő szakaszok olyan kódrészleteket nyújtanak, amelyek az Azure Communication Services telefonszám-ügyféllel kapcsolatos gyakori feladatok némelyikét fedik le. Az itt tárgyalt forgatókönyvek a következőkből állnak:

PhoneNumbersClient

SipRoutingClient

PhoneNumbersClient

Elérhető telefonszámok keresése

A beginSearchAvailablePhoneNumbers metódus használatával keressen telefonszámokat, és foglalja le őket. A visszaadott telefonszámok 15 percig vannak fenntartva, és ebben az időszakban vásárolhatók meg a searchId a beginPurchasePhoneNumbers metódusnak való megadásával.

beginSearchAvailablePhoneNumbers egy hosszú ideig futó művelet, és egy lekérdezést ad vissza.

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

A beginPurchasePhoneNumbers metódus használatával vásárolja meg a telefonszámokat a keresésből. A megvásárolt telefonszámok hozzá lesznek rendelve az ügyfél indításakor használt Communication Services-erőforráshoz. A searchId visszaadott beginSearchAvailablePhoneNumbers szükséges.

beginPurchasePhoneNumbers egy hosszú ideig futó művelet, és egy lekérdezést ad vissza.

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

Böngésszen és foglaljon le elérhető telefonszámokat

Telefonszám lefoglalása a Tallózás és foglalások API-val

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

Megvásárolt telefonszám kiadása

A beginReleasePhoneNumber metódussal kiadhat egy korábban vásárolt telefonszámot. A kiadott telefonszámok már nem lesznek társítva a Communication Services erőforráshoz, és nem lesznek elérhetők más műveletekhez (pl. SMS) az erőforrásról. A felszabadított telefonszám megadása kötelező.

beginReleasePhoneNumber egy hosszú ideig futó művelet, és egy lekérdezést ad vissza.

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

Telefonszám-képességek frissítése

A megvásárolt telefonszámok képességeinek frissítéséhez használja a beginUpdatePhoneNumberCapabilities metódust. A telefonszámok konfigurálhatók úgy, hogy támogassák a bejövő és/vagy kimenő hívásokat és sms-eket, vagy egyiket sem.

beginUpdatePhoneNumberCapabilities egy hosszú ideig futó művelet, és egy lekérdezést ad vissza.

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

Vásárolt telefonszám lekérése

A getPurchasedPhoneNumber metódussal információkat kaphat egy megvásárolt telefonszámról. Ezek az információk tartalmazzák a telefonszám típusát, képességeit, költségét és a vásárlás dátumá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);

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

Foglalás megvásárlása

Meglévő és aktív foglalás esetén vásárolja meg a foglalásban található telefonszámokat.

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

Megvásárolt telefonszámok listázása

A listPurchasedPhoneNumbers metódussal az összes megvásárolt telefonszámot átlapozza.

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

SIP-csomagok és útvonalak lekérése

Kérje le az aktuálisan konfigurált csomagtartók vagy útvonalak listáját.

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

SIP-csomagok és útvonalak cseréje

Cserélje le a jelenleg konfigurált csomagtartók vagy útvonalak listáját új értékekre.

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

Egyetlen csomagtartó lekérése

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

Egyetlen csomagtartó beállítása

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

Egyetlen csomagtartó törlése

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

Hibaelhárítás

Fakitermelés

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a AZURE_LOG_LEVEL környezeti változót info. Másik lehetőségként a naplózás futásidőben is engedélyezhető a setLogLevel meghívásával a @azure/logger:

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

Következő lépések

A kódtár használatára vonatkozó részletes példákért tekintse meg a mintákat könyvtárat.

Hozzájárulás

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót, amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

  • Last updated on