クイック スタート: Azure Communication Services を使用して任意の電話番号のオペレーター情報を検索する

重要

Azure Communication Services のこの機能は、現在プレビュー段階にあります。

プレビューの API と SDK は、サービス レベル アグリーメントなしに提供されます。 運用環境のワークロードには使用しないことをお勧めします。 一部の機能はサポート対象ではなく、機能が制限されることがあります。

詳細については、「Microsoft Azure プレビューの追加利用規約」を確認してください。

JavaScript 用の Phone Numbers クライアント ライブラリを使って、電話番号に対するオペレーター情報を検索します。この情報を使って、その電話番号との通信の有無と通信方法を決定できます。 次の手順のようにして、パッケージをインストールし、電話番号に関するオペレーター情報を検索します。

注意

このクイックスタートのコードは GitHub にあります。

前提条件

前提条件のチェック

ターミナルまたはコマンド ウィンドウで node --version コマンドを実行して、Node.js がインストールされていることを確認します。

設定

検索クエリを送信するための環境を設定するには、次のセクションの手順のようにします。

新しい Node.js アプリケーションを作成する

ターミナルまたはコマンド ウィンドウで、自分のアプリ用に新しいディレクトリを作成し、そこに移動します。

mkdir number-lookup-quickstart && cd number-lookup-quickstart

既定の設定で npm init -y を実行して、package.json ファイルを作成します。

npm init -y

作成したディレクトリのルートに、number-lookup-quickstart.js というファイルを作成します。 そこに次のスニペットを追加します。

async function main() {
    // quickstart code will go here
}

main();

パッケージをインストールする

npm install コマンドを使用して、JavaScript 用の Azure Communication Services Phone Numbers クライアント ライブラリをインストールします。

npm install @azure/communication-phone-numbers@1.3.0-beta.4 --save

--save オプションを使用すると、--save ファイル内の依存関係としてライブラリが追加されます。

コード例

クライアントを認証する

クライアント ライブラリから PhoneNumbersClient をインポートし、接続文字列を使用してインスタンスを作成します。これは、Azure portal の Azure Communication Services リソースから取得できます。 コード内に接続文字列がプレーン テキストで含まれることがないよう、COMMUNICATION_SERVICES_CONNECTION_STRING 環境変数を使うことをお勧めします。 リソースの接続文字列を管理する方法について確認してください。

number-lookup-quickstart.js の先頭に次のコードを追加します。

const { PhoneNumbersClient } = require('@azure/communication-phone-numbers');

// This code retrieves your connection string from an environment variable
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the phone numbers client
const phoneNumbersClient = new PhoneNumbersClient(connectionString);

電話番号の書式を調べる

電話番号のオペレーター情報を検索するには、PhoneNumbersClientsearchOperatorInformation を呼び出します。

let formattingResults = await phoneNumbersClient.searchOperatorInformation([ "<target-phone-number>" ]);

<target-phone-number> を、検索する電話番号 (通常はメッセージを送信する番号) に置き換えます。

警告

電話番号は、E.164 国際標準形式 (例: +14255550123) で指定します。

番号でオペレーター情報を検索する

電話番号のオペレーター情報を検索するには、PhoneNumbersClient から searchOperatorInformation を呼び出し、includeAdditionalOperatorDetails オプションで true を渡します。

let searchResults = await phoneNumbersClient.searchOperatorInformation([ "<target-phone-number>" ], { "includeAdditionalOperatorDetails": true });

警告

この機能を使用すると、アカウントに対して料金が発生します。

オペレーター情報を使用する

これで、オペレーター情報を使用できるようになりました。 このクイックスタート ガイドでは、詳細の一部をコンソールに出力します。

最初に、番号の書式に関する詳細を出力できます。

let formatInfo = formattingResults.values[0];
console.log(formatInfo.phoneNumber + " is formatted " + formatInfo.internationalFormat + " internationally, and " + formatInfo.nationalFormat + " nationally");

次に、電話番号とオペレーターに関する詳細を出力できます。

let operatorInfo = searchResults.values[0];
console.log(operatorInfo.phoneNumber + " is a " + (operatorInfo.numberType ? operatorInfo.numberType : "unknown") + " number, operated in "
    + operatorInfo.isoCountryCode + " by " + (operatorInfo.operatorDetails.name ? operatorInfo.operatorDetails.name : "an unknown operator"));

オペレーター情報を使って、SMS を送信するかどうかを判断することもできます。 SMS の送信について詳しくは、SMS のクイックスタートに関する記事をご覧ください。

コードの実行

node コマンドを使用して、ターミナルまたはコマンド ウィンドウからアプリケーションを実行します。

node number-lookup-quickstart.js

サンプル コード

サンプル アプリは GitHub からダウンロードできます。

C# 用の Phone Numbers クライアント ライブラリを使って、電話番号に対するオペレーター情報を検索します。この情報を使って、その電話番号との通信の有無と通信方法を決定できます。 次の手順のようにして、パッケージをインストールし、電話番号に関するオペレーター情報を検索します。

注意

このクイックスタートのコードは GitHub にあります。

前提条件

前提条件のチェック

ターミナルまたはコマンド ウィンドウで dotnet コマンドを実行して、.NET SDK がインストールされていることを確認します。

設定

検索クエリを送信するための環境を設定するには、次のセクションの手順のようにします。

新しい C# アプリケーションを作成する

ターミナルまたはコマンド ウィンドウで、dotnet new コマンドを実行し、NumberLookupQuickstart という名前で新しいコンソール アプリを作成します。 このコマンドにより、1 つのソース ファイル (Program.cs) を含む単純な "Hello World" C# プロジェクトが作成されます。

dotnet new console -o NumberLookupQuickstart

新しく作成したアプリ フォルダーにディレクトリを変更し、dotnet build コマンドを使用してアプリケーションをコンパイルします。

cd NumberLookupQuickstart
dotnet build

開発パッケージ フィードに接続する

SDK のパブリック プレビュー バージョンは、開発パッケージ フィードに発行されます。 NuGet CLI を使用して開発フィードを追加すると、開発フィードが NuGet.Config ファイルに追加されます。

nuget sources add -Name "Azure SDK for .NET Dev Feed" -Source "https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-net/nuget/v3/index.json"

開発フィードに接続するための詳細情報とその他のオプションについては、「貢献ガイド」をご覧ください。

パッケージをインストールする

まだアプリケーション ディレクトリにいる間に、次のコマンドを使って、Azure Communication Services PhoneNumbers クライアント ライブラリの .NET 用パッケージをインストールします。

dotnet add package Azure.Communication.PhoneNumbers --version 1.3.0-beta.5

Program.cs の先頭に using ディレクティブを追加して、Azure.Communication 名前空間を含めます。

using System;
using System.Threading.Tasks;
using Azure.Communication.PhoneNumbers;

Main の関数シグネチャを非同期となるように更新します。

internal class Program
{
    static async Task Main(string[] args)
    {
        ...
    }
}

コード例

クライアントを認証する

Phone Number クライアントは、Azure portal で Azure Communication Services リソースから取得した接続文字列を使用して認証できます。 コード内に接続文字列がプレーン テキストで含まれることがないよう、COMMUNICATION_SERVICES_CONNECTION_STRING 環境変数を使うことをお勧めします。 リソースの接続文字列を管理する方法について確認してください。

// This code retrieves your connection string from an environment variable.
string? connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");

PhoneNumbersClient client = new PhoneNumbersClient(connectionString, new PhoneNumbersClientOptions(PhoneNumbersClientOptions.ServiceVersion.V2024_03_01_Preview));

Phone Number クライアントは Microsoft Entra 認証を使用して認証することもできます。 このオプションでは、AZURE_CLIENT_SECRETAZURE_CLIENT_IDAZURE_TENANT_ID の各環境変数を認証用に設定する必要があります。

// Get an endpoint to our Azure Communication Services resource.
Uri endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);

電話番号の書式を調べる

番号の国内および国際書式を調べるには、PhoneNumbersClient から SearchOperatorInformationAsync を呼び出します。

OperatorInformationResult formattingResult = await client.SearchOperatorInformationAsync(new[] { "<target-phone-number>" });

<target-phone-number> を、検索する電話番号 (通常はメッセージを送信する番号) に置き換えます。

警告

電話番号は、E.164 国際標準形式 (例: +14255550123) で指定します。

番号でオペレーター情報を検索する

電話番号のオペレーター情報を検索するには、PhoneNumbersClient から SearchOperatorInformationAsync を呼び出し、IncludeAdditionalOperatorDetails オプションで true を渡します。

OperatorInformationResult searchResult = await client.SearchOperatorInformationAsync(new[] { "<target-phone-number>" }, new OperatorInformationOptions() { IncludeAdditionalOperatorDetails = true });

警告

この機能を使用すると、アカウントに対して料金が発生します。

オペレーター情報を使用する

これで、オペレーター情報を使用できるようになりました。 このクイックスタート ガイドでは、詳細の一部をコンソールに出力します。

最初に、番号の書式に関する詳細を出力できます。

OperatorInformation formattingInfo = formattingResult.Values[0];
Console.WriteLine($"{formattingInfo.PhoneNumber} is formatted {formattingInfo.InternationalFormat} internationally, and {formattingInfo.NationalFormat} nationally");

次に、電話番号とオペレーターに関する詳細を出力できます。

OperatorInformation operatorInformation = searchResult.Values[0];
Console.WriteLine($"{operatorInformation.PhoneNumber} is a {operatorInformation.NumberType ?? "unknown"} number, operated in {operatorInformation.IsoCountryCode} by {operatorInformation.OperatorDetails.Name ?? "an unknown operator"}");

オペレーター情報を使って、SMS を送信するかどうかを判断することもできます。 SMS の送信について詳しくは、SMS のクイックスタートに関する記事をご覧ください。

コードの実行

dotnet run コマンドを使用して、ターミナルまたはコマンド ウィンドウからアプリケーションを実行します。

dotnet run --interactive

サンプル コード

サンプル アプリは GitHub からダウンロードできます。

Java 用の Phone Numbers クライアント ライブラリを使って、電話番号に対するオペレーター情報を検索します。この情報を使って、その電話番号との通信の有無と通信方法を決定できます。 次の手順のようにして、パッケージをインストールし、電話番号に関するオペレーター情報を検索します。

注意

このクイックスタートのコードは GitHub にあります。

前提条件

前提条件のチェック

ターミナルまたはコマンド ウィンドウで mvn -v コマンドを実行して、Maven がインストールされていることを確認します。

設定

検索クエリを送信するための環境を設定するには、次のセクションの手順のようにします。

新しい Java アプリケーションを作成する

ターミナルまたはコマンド ウィンドウで、Java アプリケーションを作成するディレクトリに移動します。 次のコマンドを実行して、maven-archetype-quickstart テンプレートから Java プロジェクトを生成します。

mvn archetype:generate -DgroupId=com.communication.lookup.quickstart -DartifactId=communication-lookup-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

"generate" タスクによって、artifactId 値と同じ名前のディレクトリが作成されます。 このディレクトリの下の src/main/java ディレクトリにはプロジェクトのソース コードが含まれており、 src/test/java directory にはテスト ソースが含まれており、pom.xml ファイルはプロジェクトのプロジェクト オブジェクト モデル (POM) です。

開発パッケージ フィードに接続する

SDK のパブリック プレビュー バージョンは、開発パッケージ フィードに発行されます。 開発フィードに接続するには、テキスト エディターで pom.xml ファイルを開き、pom.xml の <repositories><distributionManagement> セクション (まだ存在しない場合は追加できる) の両方に開発リポジトリを追加します。

<repository>
  <id>azure-sdk-for-java</id>
  <url>https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-java/maven/v1</url>
  <releases>
    <enabled>true</enabled>
  </releases>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
</repository>

${user.home}/.m2settings.xml ファイルを追加または編集する必要がある場合があります

<server>
  <id>azure-sdk-for-java</id>
  <username>azure-sdk</username>
  <password>[PERSONAL_ACCESS_TOKEN]</password>
</server>

Packaging 読み取り/書き込みスコープを使用して、個人用アクセス トークンを生成し、<password> タグに貼り付けることができます。

開発フィードに接続するための詳細情報とその他のオプションについては、こちらをご覧ください。

パッケージをインストールする

pom.xml ファイルで、依存関係のグループに、次の dependency 要素を追加します。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version>1.0.0</version>
  </dependency>

  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-phonenumbers</artifactId>
    <version>1.2.0-beta.3</version>
  </dependency>

  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.2.3</version>
  </dependency>

  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core</artifactId>
    <version>1.41.0</version>
  </dependency>
</dependencies>

properties セクションを確認して、プロジェクトが Maven バージョン 1.8 以降を対象としていることを確かめます。

<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>

コード例

アプリのフレームワークを設定する

プロジェクト ディレクトリで次の操作を行います。

  1. /src/main/java/com/communication/lookup/quickstart ディレクトリに移動します
  2. 使用しているエディターで App.java ファイルを開きます
  3. System.out.println("Hello world!"); ステートメントを置き換えます
  4. import ディレクティブを追加します

次のコードを使用して開始します。

package com.communication.lookup.quickstart;

import com.azure.communication.phonenumbers.*;
import com.azure.communication.phonenumbers.models.*;
import com.azure.core.http.rest.*;
import com.azure.core.util.Context;
import com.azure.identity.*;
import java.io.*;
import java.util.ArrayList;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Number Lookup Quickstart");
        // Quickstart code goes here
    }
}

クライアントを認証する

クライアントは、Azure portal で Azure Communication Services リソースから取得した接続文字列を使用して認証できます。 コード内に接続文字列がプレーン テキストで含まれることがないよう、COMMUNICATION_SERVICES_CONNECTION_STRING 環境変数を使うことをお勧めします。 リソースの接続文字列を管理する方法について確認してください。

// This code retrieves your connection string from an environment variable
String connectionString = System.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING");

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .connectionString(connectionString)
    .buildClient();

または、Microsoft Entra 認証を使用して認証することもできます。 DefaultAzureCredentialBuilder を使用することは、Microsoft Entra ID の使用を開始する最も簡単な方法です。 Azure portal の Azure Communication Services リソースからリソース名を取得できます。

// You can find your resource name from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

電話番号の書式を調べる

番号の国内および国際書式を調べるには、PhoneNumbersClient から searchOperatorInformation を呼び出します。

ArrayList<String> phoneNumbers = new ArrayList<String>();
phoneNumbers.add("<target-phone-number>");

// Use the free number lookup functionality to get number formatting information
OperatorInformationResult formattingResult = phoneNumberClient.searchOperatorInformation(phoneNumbers);
OperatorInformation formattingInfo = formattingResult.getValues().get(0);

<target-phone-number> を、検索する電話番号 (通常はメッセージを送信する番号) に置き換えます。

警告

電話番号は、E.164 国際標準形式 (例: +14255550123) で指定します。

番号でオペレーター情報を検索する

電話番号のオペレーター情報を検索するには、PhoneNumbersClient から searchOperatorInformationWithResponse を呼び出し、IncludeAdditionalOperatorDetails オプションで true を渡します。

OperatorInformationOptions options = new OperatorInformationOptions();
options.setIncludeAdditionalOperatorDetails(true);
Response<OperatorInformationResult> result = phoneNumberClient.searchOperatorInformationWithResponse(phoneNumbers, options, Context.NONE);
OperatorInformation operatorInfo = result.getValue().getValues().get(0);

警告

この機能を使用すると、アカウントに対して料金が発生します。

オペレーター情報を使用する

これで、オペレーター情報を使用できるようになりました。 このクイックスタート ガイドでは、詳細の一部をコンソールに出力します。

最初に、番号の書式に関する詳細を出力できます。

System.out.println(formattingInfo.getPhoneNumber() + " is formatted "
    + formattingInfo.getInternationalFormat() + " internationally, and "
    + formattingInfo.getNationalFormat() + " nationally");

次に、電話番号とオペレーターに関する詳細を出力できます。

String numberType = operatorInfo.getNumberType() == null ? "unknown" : operatorInfo.getNumberType().toString();
String operatorName = "an unknown operator";
if (operatorInfo.getOperatorDetails()!= null && operatorInfo.getOperatorDetails().getName() != null)
{
    operatorName = operatorInfo.getOperatorDetails().getName();
}
System.out.println(operatorInfo.getPhoneNumber() + " is a " + numberType + " number, operated in "
    + operatorInfo.getIsoCountryCode() + " by " + operatorName);

オペレーター情報を使って、SMS を送信するかどうかを判断することもできます。 SMS の送信について詳しくは、SMS のクイックスタートに関する記事をご覧ください。

コードの実行

次のコマンドを使用して、ターミナルまたはコマンド ウィンドウからアプリケーションを実行します。pom.xml ファイルを含むディレクトリに移動し、プロジェクトをコンパイルします。

mvn compile

次に、パッケージをビルドします。

mvn package

アプリを実行するには、mvn コマンドを使用します。

mvn exec:java -D"exec.mainClass"="com.communication.lookup.quickstart.App" -D"exec.cleanupDaemonThreads"="false"

サンプル コード

サンプル アプリは GitHub からダウンロードできます。

Python 用の Phone Numbers クライアント ライブラリを使って、電話番号に対するオペレーター情報を検索します。この情報を使って、その電話番号との通信の有無と通信方法を決定できます。 次の手順のようにして、パッケージをインストールし、電話番号に関するオペレーター情報を検索します。

注意

このクイックスタートのコードは GitHub にあります。

前提条件

前提条件のチェック

ターミナルまたはコマンド ウィンドウで python --version コマンドを実行して、Python がインストールされていることを確認します。

設定

検索クエリを送信するための環境を設定するには、次のセクションの手順のようにします。

新しい Python アプリケーションを作成する

ターミナルまたはコマンド ウィンドウで、自分のアプリ用に新しいディレクトリを作成し、そこに移動します。

mkdir number-lookup-quickstart && cd number-lookup-quickstart

テキスト エディターを使用して number_lookup_sample.py というファイルをプロジェクトのルート ディレクトリに作成し、次のコードを追加します。 残りのクイックスタート コードは、以降のセクションで追加されます。

import os
from azure.communication.phonenumbers import PhoneNumbersClient

try:
   print('Azure Communication Services - Number Lookup Quickstart')
   # Quickstart code goes here
except Exception as ex:
   print('Exception:')
   print(ex)

パッケージをインストールする

引き続きアプリケーション ディレクトリで、pip install コマンドを使用して、Python 用の Azure Communication Services PhoneNumbers クライアント ライブラリ パッケージをインストールします。

pip install azure-communication-phonenumbers==1.2.0b2

コード例

クライアントを認証する

クライアントは、Azure portal で Azure Communication Services リソースから取得した接続文字列を使用して認証できます。 コード内に接続文字列がプレーン テキストで含まれることがないよう、COMMUNICATION_SERVICES_CONNECTION_STRING 環境変数を使うことをお勧めします。 リソースの接続文字列を管理する方法について確認してください。

# This code retrieves your connection string from an environment variable
connection_string = os.getenv('COMMUNICATION_SERVICES_CONNECTION_STRING')
try:
    phone_numbers_client = PhoneNumbersClient.from_connection_string(connection_string)
except Exception as ex:
    print('Exception:')
    print(ex)

または、Microsoft Entra 認証を使用してクライアントを認証することもできます。 DefaultAzureCredential オブジェクトを使用するのが、Microsoft Entra ID を開始する最も簡単な方法です。これは、pip install コマンドを使用してインストールできます。

pip install azure-identity

DefaultAzureCredential オブジェクトを作成するためには、登録済みの Microsoft Entra アプリケーションと対応する値であらかじめ AZURE_CLIENT_IDAZURE_CLIENT_SECRETAZURE_TENANT_ID を環境変数として設定しておく必要があります。

これらの環境変数を取得する方法については、CLI からサービス プリンシパルを設定する方法を参照してください。

azure-identity ライブラリがインストールされたら、クライアントの認証を続行できます。

from azure.identity import DefaultAzureCredential

# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
    credential = DefaultAzureCredential()
    phone_numbers_client = PhoneNumbersClient(endpoint, credential)
except Exception as ex:
    print('Exception:')
    print(ex)

電話番号の書式を調べる

番号の国内および国際書式を調べるには、PhoneNumbersClient から search_operator_information を呼び出します。

formatting_results = phone_numbers_client.search_operator_information("<target-phone-number>")

<target-phone-number> を、検索する電話番号 (通常はメッセージを送信する番号) に置き換えます。

警告

電話番号は、E.164 国際標準形式 (例: +14255550123) で指定します。

番号でオペレーター情報を検索する

電話番号のオペレーター情報を検索するには、PhoneNumbersClient から search_operator_information を呼び出し、include_additional_operator_details オプションで True を渡します。

options = { "include_additional_operator_details": True }
operator_results = phone_numbers_client.search_operator_information("<target-phone-number>", options)

警告

この機能を使用すると、アカウントに対して料金が発生します。

オペレーター情報を使用する

これで、オペレーター情報を使用できるようになりました。 このクイックスタート ガイドでは、詳細の一部をコンソールに出力します。

最初に、番号の書式に関する詳細を出力できます。

formatting_info = formatting_results.values[0]
print(str.format("{0} is formatted {1} internationally, and {2} nationally", formatting_info.phone_number, formatting_info.international_format, formatting_info.national_format))

次に、電話番号とオペレーターに関する詳細を出力できます。

operator_information = operator_results.values[0]

number_type = operator_information.number_type if operator_information.number_type else "unknown"
if operator_information.operator_details is None or operator_information.operator_details.name is None:
    operator_name = "an unknown operator"
else:
    operator_name = operator_information.operator_details.name

print(str.format("{0} is a {1} number, operated in {2} by {3}", operator_information.phone_number, number_type, operator_information.iso_country_code, operator_name))

オペレーター情報を使って、SMS を送信するかどうかを判断することもできます。 SMS の送信について詳しくは、SMS のクイックスタートに関する記事をご覧ください。

コードの実行

python コマンドを使用して、ターミナルまたはコマンド ウィンドウからアプリケーションを実行します。

python number_lookup_sample.py

サンプル コード

サンプル アプリは GitHub からダウンロードできます。

トラブルシューティング

よくある質問と問題:

  • 環境変数の変更は、既に実行されているプログラムでは有効にならない場合があります。 環境変数が期待どおりに動作しないことに気付いた場合は、コードの実行と編集に使用しているプログラムを閉じてから再度開いてみてください。
  • このエンドポイントによって返されるデータは、さまざまな国際法と規制の対象となるため、結果の正確さはいくつかの要因によって異なります。 このような要因としては、番号が移植されているかどうか、国番号、呼び出し元の承認状態などがあります。 これらの要因によっては、オペレーター情報が、一部の電話番号で使用できない場合や、電話番号の現在のオペレーターではなく元のオペレーターを反映している場合があります。

次の手順

このクイック スタートでは、次の方法について説明しました。

  • 番号の書式を調べる
  • 電話番号でオペレーター情報を検索する