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

電話番号ライブラリには、電話番号管理用の機能が用意されています。

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

作業の開始

前提条件

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

［インストール中］

npm install @azure/communication-phone-numbers

ブラウザーのサポート

JavaScript バンドル

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

主要な概念

電話番号パッケージは、電話番号を PhoneNumbersClient 管理するメソッドを提供する を公開します。

電話番号の種類

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

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

数値の検索と取得

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

電話番号の構成

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

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

例

認証

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

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

キーを取得したら、次のいずれかの方法で を PhoneNumbersClient 認証できます。

接続文字列の使用

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(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);

Azure Active Directory 資格情報の使用

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

npm install @azure/identity

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

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

let credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

使用方法

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

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

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

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

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

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const searchRequest = {
    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 = searchPoller.pollUntilDone();
  console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
  console.log(`searchId: ${searchResults.searchId}`);
}

main();

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

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

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

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const searchRequest = {
    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 } = searchPoller.pollUntilDone();

  const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

  // Purchase is underway.
  await purchasePoller.pollUntilDone();
  console.log(`Successfully purchased ${phoneNumbers[0]}`);
}

main();

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

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

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

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const phoneNumberToRelease = "<phone-number-to-release>";

  const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

  // Release is underway.
  await releasePoller.pollUntilDone();
  console.log("Successfully release phone number.");
}

main();

電話番号機能を更新する

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

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

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async function main() {
  const phoneNumberToUpdate = "<phone-number-to-update>";

  // This will update phone number to send and receive sms, but only send calls.
  const updateRequest = {
    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}`);
}

main();

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

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

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async main function() {
  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}`);
}

main();

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

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

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

async main function() {
  const phoneNumbers = await 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}`);
  }
}

main();

トラブルシューティング

次のステップ

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

共同作成

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

関連プロジェクト

• Microsoft Azure SDK for Javascript