JavaScript 用 Azure Communication Phone Numbers クライアントライブラリ - バージョン 1.5.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番号には、地理的、Toll-Free、モバイルの 3 種類があります。地理的および携帯電話プランは、場所に関連付けられた電話プランであり、その電話番号の市外局番は地理的な場所の市外局番に関連付けられています。 Toll-Free 電話プランは、関連付けられていない場所の電話プランです。たとえば、米国では、フリーダイヤル番号に 800 や 888 などの市区電話が付属している場合があります。これらは、PhoneNumbersClient を使用して管理されます

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

電話番号クライアント

電話番号の種類

電話番号には 3 つのタイプがあります。地理的、Toll-Free 的、モバイル。 Toll-Free 番号はロケーションに関連付けられていません。たとえば、米国では、フリーダイヤル番号に 800 や 888 などの市区電話が付属している場合があります。地理的電話番号と携帯電話番号は、場所に関連付けられた電話番号です。

同じ国の電話番号タイプは、その電話番号タイプの電話プラングループにグループ化されます。たとえば、同じ国内 Toll-Free すべての電話番号は、電話プラングループにグループ化されます。

数値の検索と取得

電話番号は、電話番号の種類 (地理的、フリーダイヤル、またはモバイル)、割り当ての種類 (個人またはアプリケーション)、通話および SMS 機能、市外局番、電話番号の数を指定することで、検索作成 API を通じて検索できます。指定された電話番号の数量は、15 分間予約されます。電話番号のこの検索は、取り消すか購入することができます。検索が取り消されると、電話番号は他のユーザーが利用できるようになります。検索が購入されると、Azure リソースの電話番号が取得されます。

電話番号の構成

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

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

電話番号の閲覧と予約

Browse API と Reservations API は、ショッピングカートのようなエクスペリエンスを通じて電話番号を取得する別の方法を提供します。これは、1 つの LRO を使用して番号を検索して予約する検索操作を、参照と予約の 2 つの別々の同期ステップに分割することで実現されます。

参照操作では、特定の国で購入可能な電話番号のランダムサンプルが取得され、結果を絞り込むためのオプションのフィルター処理条件が使用されます。返された電話番号は、どの顧客にも予約されていません。

予約は、特定の顧客によってロックされ、購入を待っている電話番号のコレクションを表します。有効期限は、最後の変更から 15 分後、または作成時刻から 2 時間後です。予約には、検索操作とは対照的に、さまざまな国の番号を含めることができます。お客様は、予約の作成、取得、変更 (番号の追加と削除)、削除、および購入を行うことができます。予約の購入はLROです。

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 の電話番号クライアントを使用する一般的なタスクの一部を説明するコードスニペットを示します。ここで説明するシナリオは、次のもので構成されます。

電話番号クライアント

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

SipRoutingClient の略

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

電話番号クライアント

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

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

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 リソースに割り当てられます。 searchId から返される beginSearchAvailablePhoneNumbers が必要です。

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

利用可能な電話番号の閲覧と予約

Browse and Reservations API を使用して電話番号を予約する

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

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

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

購入予約

既存のアクティブな予約がある場合は、その予約の電話番号を購入します。

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

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

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に設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

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

setLogLevel("info");

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

次の手順

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

貢献

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

Microsoft Azure SDK for Javascript の

フィードバック

このページはお役に立ちましたか?

最終更新: 2025-08-29

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

はじめ

前提 条件

装着

ブラウザーのサポート

JavaScript バンドル

主な概念

電話番号クライアント

電話番号の種類

数値の検索と取得

電話番号の構成

電話番号の閲覧と予約

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

例

認証

接続文字列の使用

AzureKeyCredential でのアクセス キーの使用

Azure Active Directory 資格情報の使用

使い

電話番号クライアント

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

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

利用可能な電話番号の閲覧と予約

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

電話番号機能を更新する

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

購入予約

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

SipRoutingClient の略

SIP トランクとルートを取得する

SIP トランクとルートを交換する

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

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

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

トラブルシューティング

伐採

次の手順

貢献

関連プロジェクト

フィードバック

その他のリソース

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

前提条件

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

`AzureKeyCredential` でのアクセスキーの使用