Aracılığıyla paylaş

JavaScript için Azure İletişim Telefon Numaraları istemci kitaplığı - sürüm 1.5.0

Telefon numaraları kitaplığı, telefon numarası yönetimi için özellikler sağlar.

Satın alınan telefon numaraları ülkeye, numara türüne ve atama türüne bağlı olarak birçok özelliğe sahip olabilir. Özelliklere örnek olarak SMS gelen ve giden kullanımı, PSTN gelen ve giden kullanımı verilebilir. Telefon numaraları, web kancası URL'si aracılığıyla bota da atanabilir.

Başlarken

Önkoşullar

Yükleme

npm install @azure/communication-phone-numbers

Tarayıcı desteği

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için önce bir paketleyici kullanmanız gerekir. Bunun nasıl yapılacağının ayrıntıları için lütfen paketleme belgelerimize bakın.

Temel kavramlar

Bu SDK, direct offer ve direct routing numaralarını kolayca yönetmeye yönelik işlevler sağlar.

Sayılar direct offer üç türde gelir: Coğrafi, Toll-Free ve Mobil. Coğrafi ve Cep telefonu planları, telefon numaralarının alan kodları bir coğrafi konumun alan koduyla ilişkilendirilen bir konumla ilişkili telefon planlarıdır. Toll-Free telefon planları, ilişkili konum olmayan telefon planlarıdır. Örneğin, ABD'de ücretsiz numaralar 800 veya 888 gibi alan kodlarıyla birlikte gelebilir. Bunlar PhoneNumbersClient kullanılarak yönetilir

direct routing özelliği, mevcut telefon altyapınızı ACS'ye bağlamanızı sağlar. Yapılandırma, telefon alt ağınıza yönelik çağrıları düzgün bir şekilde işlemek için SIP gövdelerini ve ses yönlendirme kurallarını ayarlama yöntemlerini sağlayan SipRoutingClientkullanılarak yönetilir.

Telefon numaraları istemcisi

Telefon numarası türleri

Telefon numaraları üç türde gelir; Coğrafi, Toll-Free ve mobil. Toll-Free numaraları bir konumla ilişkilendirilmemiştir. Örneğin, ABD'de ücretsiz numaralar 800 veya 888 gibi alan kodlarıyla birlikte gelebilir. Coğrafi ve Cep telefonu numaraları, bir konumla ilişkili telefon numaralarıdır.

Aynı ülkeye sahip telefon numarası türleri, söz konusu telefon numarası türüne sahip bir telefon tarifesi grubunda gruplandırılır. Örneğin, aynı ülkedeki tüm Toll-Free telefon numaraları bir telefon planı grubunda gruplandırılır.

Numaraları arama ve alma

Telefon numaraları, bir telefon numarası türü (coğrafi, ücretsiz veya mobil), atama türü (kişi veya uygulama), arama ve sms özellikleri, bir alan kodu ve telefon numarası miktarı sağlanarak arama oluşturma API'si aracılığıyla aranabilir. Sağlanan telefon numarası miktarı 15 dakika boyunca ayrılacaktır. Bu telefon numarası araması iptal edilebilir veya satın alınabilir. Arama iptal edilirse, telefon numaraları başkaları tarafından kullanılabilir hale gelir. Arama satın alınırsa, Azure kaynağı için telefon numaraları alınır.

Telefon numaralarını yapılandırma

Telefon numaraları, özelliklerin bir bileşimine sahip olabilir. Bunlar gelen ve/veya giden aramayı destekleyecek şekilde yapılandırılabilir veya arama için telefon numarasını kullanmayacaksanız yapılandırılabilir. Aynı durum sms özellikleri için de geçerlidir.

Telefon numaranızın atama türünü göz önünde bulundurmanız önemlidir. Bazı özellikler belirli bir atama türüyle sınırlıdır.

Telefon numaralarına göz atma ve rezerve etme

Gözat ve Rezervasyonlar API'leri, alışveriş sepeti benzeri bir deneyim aracılığıyla telefon numaraları almak için alternatif bir yol sağlar. Bu, tek bir LRO kullanarak numaraları bulan ve rezerve eden arama işleminin, Gözat ve Rezervasyon olmak üzere iki ayrı zaman uyumlu adıma bölünmesiyle elde edilir.

Gözatma işlemi, sonuçları daraltmak için isteğe bağlı filtreleme ölçütleriyle birlikte belirli bir ülke için satın alınabilecek rastgele bir telefon numarası örneği alır. İade edilen telefon numaraları herhangi bir müşteri için rezerve edilmemiştir.

Rezervasyonlar, belirli bir müşteri tarafından kilitlenen ve satın alınmayı bekleyen telefon numaralarından oluşan bir koleksiyonu temsil eder. Son değişiklikten sonra 15 dakika veya oluşturma zamanından itibaren 2 saatlik bir sona erme süreleri vardır. Rezervasyon, Arama işleminin aksine farklı ülkelerden numaralar içerebilir. Müşteriler rezervasyon oluşturabilir, alabilir, değiştirebilir (numara ekleyip kaldırarak), silebilir ve satın alabilir. Rezervasyon satın almak bir LRO'dur.

SIP yönlendirme istemcisi

Doğrudan yönlendirme özelliği, müşteri tarafından sağlanan telefon altyapısının Azure İletişim Kaynaklarına bağlanmasına olanak tanır. Yönlendirme yapılandırmasını düzgün bir şekilde ayarlamak için müşterinin çağrılar için SIP gövde yapılandırmasını ve SIP yönlendirme kurallarını sağlaması gerekir. SIP yönlendirme istemcisi bu yapılandırmayı ayarlamak için gerekli arabirimi sağlar.

Bir çağrı yapıldığında sistem, hedef numarayı tanımlı yolların regex sayı desenleriyle eşleştirmeye çalışır. Sayıyla eşleşen ilk yol seçilir. Regex eşleştirme sırası, yapılandırmadaki yolların sırasıyla aynıdır, bu nedenle yolların sırası önemlidir. Bir yol eşleştirildikten sonra çağrı, rotanın gövdeler listesindeki ilk gövdeye yönlendirilir. Gövde kullanılamıyorsa, listede bir sonraki gövde seçilir.

Örnekler

Kimlik doğrulama

İletişim Hizmetleri API'sine erişmek üzere bir istemci nesnesi oluşturmak için, İletişim Hizmetleri kaynağınızın bir connection string veya endpoint ve bir credentialgerekir. Telefon Numaraları istemcisi kimlik doğrulaması için Azure Active Directory kimlik bilgilerini veya API anahtarı kimlik bilgilerini kullanabilir.

Azure Portalİletişim Hizmetleri kaynağınızdan bir anahtar ve/veya bağlantı dizesi alabilirsiniz. İletişim Hizmetleri kaynağınızın uç noktasını Azure Portalde bulabilirsiniz.

Anahtarınız olduktan sonra istemcinin kimliğini aşağıdaki yöntemlerden biriyle doğrulayabilirsiniz:

Bağlantı dizesi kullanma

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

AzureKeyCredential ile erişim anahtarı kullanma

İstemciyi başlatmak için bir anahtar kullanırsanız uygun uç noktayı da sağlamanız gerekir. Bu uç noktayı Azure Portalİletişim Hizmetleri kaynağınızdan alabilirsiniz. Anahtarınız ve uç noktanız olduktan sonra aşağıdaki kodla kimlik doğrulaması yapabilirsiniz:

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 Kimlik Bilgilerini Kullanma

Bağlantı dizesi kimlik doğrulaması örneklerin çoğunda kullanılır, ancak Azure Kimlik kitaplığınıkullanarak Azure Active Directory ile kimlik doğrulaması da yapabilirsiniz. Aşağıda gösterilen DefaultAzureCredential sağlayıcısını veya Azure SDK ile sağlanan diğer kimlik bilgisi sağlayıcılarını kullanmak için lütfen @azure/identity paketini yükleyin:

npm install @azure/identity

@azure/identity paketi, uygulamanızın bunu yapmak için kullanabileceği çeşitli kimlik bilgisi türleri sağlar. @azure/identity için README, başlamanıza yönelik daha fazla ayrıntı ve örnek sağlar.

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

Kullanım

Aşağıdaki bölümlerde, Azure İletişim Hizmetleri Telefon Numaraları istemcisini kullanarak bazı yaygın görevleri kapsayan kod parçacıkları sağlanır. Burada ele alınan senaryolar şunlardan oluşur:

Telefon Numaralarıİstemci

SipRoutingClient

Telefon Numaralarıİstemci

Kullanılabilir telefon numaralarını arama

Telefon numaralarını aramak ve ayırmak için beginSearchAvailablePhoneNumbers yöntemini kullanın. Döndürülen telefon numaraları 15 dakika süreyle ayrılmıştır ve bu süre boyunca searchId yöntemine beginPurchasePhoneNumbers sağlanarak satın alınabilir.

beginSearchAvailablePhoneNumbers uzun süre çalışan bir işlemdir ve bir poller döndürür.

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

Aramanızdan telefon numaralarını satın almak için beginPurchasePhoneNumbers yöntemini kullanın. Satın alınan telefon numaraları, istemciyi başlatırken kullanılan İletişim Hizmetleri kaynağına atanır. searchId döndürülen beginSearchAvailablePhoneNumbers gereklidir.

beginPurchasePhoneNumbers uzun süre çalışan bir işlemdir ve bir poller döndürür.

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

Mevcut telefon numaralarına göz atın ve rezerve edin

Bir telefon numarası rezerve etmek için Göz Atma ve Rezervasyonlar API'sini kullanma

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

Satın alınan bir telefon numarasını serbest bırakma

Daha önce satın alınan bir telefon numarasını serbest bırakmak için beginReleasePhoneNumber yöntemini kullanın. Yayımlanan telefon numaraları artık İletişim Hizmetleri kaynağıyla ilişkilendirilmeyecek ve diğer işlemlerle (örn. SMS) değerini seçin. Piyasaya sürülen telefon numarası gereklidir.

beginReleasePhoneNumber uzun süre çalışan bir işlemdir ve bir poller döndürür.

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

Telefon numarası özelliklerini güncelleştirme

Satın alınan bir telefon numarasının özelliklerini güncelleştirmek için beginUpdatePhoneNumberCapabilities yöntemini kullanın. Telefon numaraları, gelen ve/veya giden arama ve sms'leri destekleyecek şekilde yapılandırılabilir ya da hiçbirini desteklemez.

beginUpdatePhoneNumberCapabilities uzun süre çalışan bir işlemdir ve bir poller döndürür.

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

Satın alınan telefon numarasını alma

Satın alınan bir telefon numarası hakkında bilgi almak için getPurchasedPhoneNumber yöntemini kullanın. Bu bilgiler telefon numarasının türünü, özelliklerini, maliyetini ve satın alma tarihini içerir.

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

Rezervasyon satın al

Mevcut ve aktif bir rezervasyon verildiğinde, bu rezervasyondaki telefon numaralarını satın alın.

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

Satın alınan telefon numaralarını listeleme

Satın alınan tüm telefon numaralarını sayfalandırmak için listPurchasedPhoneNumbers yöntemini kullanın.

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 gövdelerini ve yollarını alma

Şu anda yapılandırılmış olan gövdelerin veya yolların listesini alın.

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 gövdelerini ve yollarını değiştirme

Şu anda yapılandırılmış olan gövdelerin veya yolların listesini yeni değerlerle değiştirin.

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

Tek gövdeli gövdeyi alma

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

Tek gövde ayarlama

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

Tek gövdeli silme

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

Sorun giderme

Günlük tutmak

Günlüğe kaydetmeyi etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, setLogLevel@azure/logger çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki adımlar

Bu kitaplığın nasıl kullanılacağına ilişkin ayrıntılı örnekler için lütfen örnekleri dizinine göz atın.

Katkıda

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

  • Last updated on