JavaScript 用 Azure Communication Phone Numbers クライアント ライブラリ - バージョン 1.3.0

電話番号ライブラリは、電話番号管理の機能を提供します。

購入した電話番号には、国、番号の種類、割り当ての種類に応じて、さまざまな機能が用意されています。 機能の例としては、SMS の受信と送信の使用状況、PSTN の受信と送信の使用があります。 電話番号は、Webhook URL を使用してボットに割り当てることもできます。

はじめ

前提 条件

• Azure サブスクリプション。
• 既存の Communication Services リソース。 リソースを作成する必要がある場合は、Azure Portal、Azure PowerShell、または Azure CLIを使用できます。

装着

npm install @azure/communication-phone-numbers

ブラウザーのサポート

JavaScript バンドル

ブラウザーでこのクライアント ライブラリを使用するには、まず、バンドルを使用する必要があります。 これを行う方法の詳細については、バンドルドキュメントを参照してください。

主な概念

この SDK は、direct offer と direct routing 番号を簡単に管理する機能を提供します。

direct offer 番号には、地理とフリーダイヤルの 2 種類があります。 地理的な電話プランは、電話番号の地域コードが地理的な場所の地域コードに関連付けられている場所に関連付けられた電話プランです。 Toll-Free 電話プランは、関連付けられていない場所の電話プランです。 たとえば、米国では、フリーダイヤル番号に 800 や 888 などの市区電話が付属している場合があります。 これらは、PhoneNumbersClient を使用して管理されます

direct routing 機能を使用すると、既存のテレフォニー インフラストラクチャを ACS に接続できます。 構成は、テレフォニー サブネットの呼び出しを適切に処理するために、SIP トランクと音声ルーティング規則を設定する方法を提供する SipRoutingClientを使用して管理されます。

電話番号クライアント

電話番号の種類

電話番号は 2 種類あります。地域とフリーダイヤル。 地理的な電話番号は、地域コードが地理的な場所のエリア コードに関連付けられている場所に関連付けられている電話番号です。 Toll-Free 電話番号は場所に関連付けされません。 たとえば、米国では、フリーダイヤル番号に 800 や 888 などの市区電話が付属している場合があります。

同じ国内のすべての地理的な電話番号は、地理的な電話番号の種類を持つ電話プラン グループにグループ化されます。 同じ国内のすべての Toll-Free 電話番号は、電話プラン グループにグループ化されます。

数値の検索と取得

電話番号は、電話番号の種類 (地理的または無料)、割り当ての種類 (個人またはアプリケーション)、通話機能と SMS 機能、エリア コードと電話番号の数量を指定することで、検索作成 API を使用して検索できます。 指定された電話番号の数量は、15 分間予約されます。 電話番号のこの検索は、取り消すか購入することができます。 検索が取り消されると、電話番号は他のユーザーが利用できるようになります。 検索が購入されると、Azure リソースの電話番号が取得されます。

電話番号の構成

電話番号には、機能を組み合わせて使用できます。 着信通話または発信通話をサポートするように構成することも、通話に電話番号を使用しない場合も構成することはできません。 SMS 機能にも同じことが当てはまります。

電話番号の割り当ての種類を考慮することが重要です。 一部の機能は、特定の割り当ての種類に制限されています。

SIP ルーティング クライアント

ダイレクト ルーティング機能を使用すると、顧客が提供するテレフォニー インフラストラクチャを Azure Communication Resources に接続できます。 ルーティング構成を適切に設定するには、お客様がコールの SIP トランク設定と SIP ルーティング規則を指定する必要があります。 SIP ルーティング クライアントは、この構成を設定するために必要なインターフェイスを提供します。

呼び出しが行われると、システムは、定義されたルートの正規表現番号パターンと宛先番号の照合を試みます。 番号に一致する最初のルートが選択されます。 正規表現の一致順序は、構成内のルートの順序と同じであるため、ルートの順序が重要になります。 ルートが一致すると、呼び出しはルートのトランク リストの最初のトランクにルーティングされます。 トランクが使用できない場合は、リスト内の次のトランクが選択されます。

例

認証

Communication Services API にアクセスするためのクライアント オブジェクトを作成するには、Communication Services リソースの connection string または endpoint と credentialが必要です。 電話番号クライアントは、Azure Active Directory 資格情報または API キー資格情報を使用して認証できます。

Azure Portalで、Communication Services リソースからキーや接続文字列を取得できます。 Communication Services リソースのエンドポイントは、Azure Portalで見つけることもできます。

キーを取得したら、次のいずれかの方法でクライアントを認証できます。

接続文字列の使用

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 でのアクセス キーの使用

キーを使用してクライアントを初期化する場合は、適切なエンドポイントを指定する必要もあります。 このエンドポイントは、Azure Portal Communication Services リソースから取得できます。 キーとエンドポイントを取得したら、次のコードで認証できます。

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 資格情報の使用

接続文字列認証はほとんどの例で使用されますが、Azure ID ライブラリを使用して Azure Active Directory で認証することもできます。 以下に示す DefaultAzureCredential プロバイダー、または Azure SDK で提供されているその他の資格情報プロバイダーを使用するには、@azure/identity パッケージをインストールしてください。

npm install @azure/identity

@azure/identity パッケージには、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。 @azure/identity 用の README には、作業を開始するための詳細とサンプルが用意されています。

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

使い

次のセクションでは、Azure Communication Services の電話番号クライアントを使用する一般的なタスクの一部を説明するコード スニペットを示します。 ここで説明するシナリオは、次のもので構成されます。

PhoneNumbersClient

• 使用可能な電話番号を検索
• 検索 から電話番号を購入する
• 購入した電話番号の を解放する
• 電話番号機能の更新
• 購入した電話番号を取得
• 購入した電話番号を一覧表示する

SipRoutingClient

• SIP トランクとルート を取得する
• SIP トランクとルートを に置き換える
• 単一トランク を取得する
• 1 つのトランク を設定する
• 1 つのトランク を削除する

PhoneNumbersClient

使用可能な電話番号を検索する

beginSearchAvailablePhoneNumbers メソッドを使用して電話番号を検索し、予約します。 返される電話番号は 15 分間予約されており、beginPurchasePhoneNumbers メソッドに searchId を提供することで、この期間中に購入できます。

beginSearchAvailablePhoneNumbers は実行時間の長い操作であり、ポーリングプログラムを返します。

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

検索から電話番号を購入する

beginPurchasePhoneNumbers 方法を使用して、検索から電話番号を購入します。 購入した電話番号は、クライアントの起動時に使用される Communication Services リソースに割り当てられます。 beginSearchAvailablePhoneNumbers から返される searchId が必要です。

beginPurchasePhoneNumbers は実行時間の長い操作であり、ポーリングプログラムを返します。

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

購入した電話番号を解放する

beginReleasePhoneNumber メソッドを使用して、以前に購入した電話番号を解放します。 リリースされた電話番号は Communication Services リソースに関連付けられなくなり、他の操作 (例:SMS) を使用します。 リリースされる電話番号が必要です。

beginReleasePhoneNumber は実行時間の長い操作であり、ポーリングプログラムを返します。

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

電話番号機能を更新する

beginUpdatePhoneNumberCapabilities メソッドを使用して、購入した電話番号の機能を更新します。 電話番号は、着信通話と発信通話と SMS をサポートするように構成することも、どちらもサポートするように構成することはできません。

beginUpdatePhoneNumberCapabilities は実行時間の長い操作であり、ポーリングプログラムを返します。

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

購入した電話番号を取得する

getPurchasedPhoneNumber メソッドを使用して、購入した電話番号に関する情報を取得します。 この情報には、電話番号の種類、機能、コスト、購入日が含まれます。

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

購入した電話番号を一覧表示する

listPurchasedPhoneNumbers メソッドを使用して、購入したすべての電話番号をページングします。

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 トランクとルートを取得する

現在構成されているトランクまたはルートの一覧を取得します。

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 トランクとルートを交換する

現在構成されているトランクまたはルートの一覧を新しい値に置き換えます。

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

1 つのトランクを取得する

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

1 つのトランクを設定する

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

1 つのトランクを削除する

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

トラブルシューティング

伐採

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。 または、@azure/loggerで setLogLevel を呼び出すことによって、実行時にログを有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細な手順については、@azure/logger パッケージのドキュメントを参照してください。

次の手順

このライブラリの使用方法の詳細な例については、ディレクトリ サンプルを参照してください。

貢献

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイド を参照してください。

関連プロジェクト

• Microsoft Azure SDK for Javascript の