你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：了解如何使用 Azure 通信服务查找电话号码的运营商信息

项目
04/08/2024

重要

Azure 通信服务的这一功能目前以预览版提供。

预览版 API 和 SDK 在没有服务级别协议的情况下提供。建议不要将它们用于生产工作负荷。某些功能可能不受支持或者已受限。

有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

开始使用适用于 JavaScript 的电话号码客户端库来查找电话号码的运营商信息，这些信息可用于确定是否以及如何与该电话号码通信。按照以下步骤安装包并查找有关电话号码的运营商信息。

注意

在 GitHub 上查找此快速入门的代码。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Node.js 活动 LTS（长期支持）和维护 LTS 版本（建议使用 8.11.1 和 10.14.1）。
活动的通信服务资源和连接字符串。创建通信服务资源。

先决条件检查

在终端或命令窗口中，运行 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 通信服务电话号码客户端库。

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

--save 选项将该库作为 package.json 文件中的依赖项列出。

代码示例

验证客户端

从客户端库导入 PhoneNumbersClient，并使用连接字符串将其实例化，可从 Azure 门户中的 Azure 通信服务资源获取该字符串。建议使用 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);

查找电话号码格式

若要搜索电话号码的运营商信息，请从 PhoneNumbersClient 调用 searchOperatorInformation。

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

还可以使用运营商信息确定是否发送短信。有关发送短信的详细信息，请参阅短信快速入门。

运行代码

使用 node 命令从终端或命令窗口运行应用程序。

node number-lookup-quickstart.js

示例代码

可以从 GitHub 下载示例应用。

开始使用适用于 C# 的电话号码客户端库来查找电话号码的运营商信息，这些信息可用于确定是否以及如何与该电话号码通信。按照以下步骤安装包并查找有关电话号码的运营商信息。

注意

在 GitHub 上查找此快速入门的代码。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
适用于你的操作系统的最新版本 .NET Core 客户端库。
活动的通信服务资源和连接字符串。创建通信服务资源。

先决条件检查

在终端或命令窗口中，运行 dotnet 命令查看是否安装 .NET SDK。

设置

若要设置用于发送查找查询的环境，请执行以下部分中所述的步骤。

新建 C# 应用程序

在终端或命令窗口中，运行 dotnet new 命令创建名为 NumberLookupQuickstart 的新控制台应用。此命令将创建包含单个源文件 (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"

有关连接到开发提要的更多详细信息和其他选项，可以在参与指南中找到。

安装包

仍然是在应用程序目录中，使用以下命令安装适用于 .NET 包的 Azure 通信服务电话号码客户端库。

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

将 using 指令添加到 Program.cs 顶部以包括 Azure.Communication 命名空间。

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

将 Main 函数签名更新为 async。

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

代码示例

验证客户端

可使用从 Azure 门户中的 Azure 通信服务资源获取的连接字符串对电话号码客户端进行身份验证。建议使用 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));

电话号码客户端还可以使用 Microsoft Entra 身份验证进行身份验证。在此选项中，AZURE_CLIENT_SECRET、AZURE_CLIENT_ID 和 AZURE_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"}");

还可以使用运营商信息确定是否发送短信。有关发送短信的详细信息，请参阅短信快速入门。

运行代码

使用 dotnet run 命令从终端或命令窗口运行应用程序。

dotnet run --interactive

示例代码

可以从 GitHub 下载示例应用。

开始使用适用于 Java 的电话号码客户端库来查找电话号码的运营商信息，这些信息可用于确定是否以及如何与该电话号码通信。按照以下步骤安装包并查找有关电话号码的运营商信息。

注意

在 GitHub 上查找此快速入门的代码。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Java 开发工具包 (JDK) 8 或更高版本。
Apache Maven。
活动的通信服务资源和连接字符串。创建通信服务资源。

先决条件检查

在终端或命令窗口中，运行 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

“生成”任务将创建一个名称与 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}/.m2 中添加或编辑 settings.xml 文件

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

可以生成包含打包读写范围的个人访问令牌，并将其粘贴到 <password> 标记中。

有关连接到开发提要的更多详细信息和其他选项，可以在此处找到。

安装包

在 pom.xml 文件中，将以下依赖项元素添加到依赖项组。

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

代码示例

设置应用框架

从项目目录中执行以下操作：

导航到 /src/main/java/com/communication/lookup/quickstart 目录
在编辑器中打开 App.java 文件
替换 System.out.println("Hello world!"); 语句
添加 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 门户中的 Azure 通信服务资源获取的连接字符串对客户端进行身份验证。建议使用 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 门户中的 Azure 通信服务资源获取源名称。

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

还可以使用运营商信息确定是否发送短信。有关发送短信的详细信息，请参阅短信快速入门。

运行代码

使用以下命令从终端或命令窗口运行应用程序：导航到包含 pom.xml 文件的目录并编译项目。

mvn compile

然后，生成包。

mvn package

使用 mvn 命令执行该应用。

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

示例代码

可以从 GitHub 下载示例应用。

开始使用适用于 Python 的电话号码客户端库来查找电话号码的运营商信息，这些信息可用于确定是否以及如何与该电话号码通信。按照以下步骤安装包并查找有关电话号码的运营商信息。

注意

在 GitHub 上查找此快速入门的代码。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Python 3.7+。
活动的通信服务资源和连接字符串。创建通信服务资源。

先决条件检查

在终端或命令窗口中，运行 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 通信服务 PhoneNumbers 客户端库。

pip install azure-communication-phonenumbers==1.2.0b2

代码示例

对客户端进行身份验证

# 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_ID、AZURE_CLIENT_SECRET 和 AZURE_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))

还可以使用运营商信息确定是否发送短信。有关发送短信的详细信息，请参阅短信快速入门。

运行代码

使用 python 命令从终端或命令窗口运行应用程序。

python number_lookup_sample.py

示例代码

可以从 GitHub 下载示例应用。

疑难解答

常见问题：

对环境变量的更改可能不会在正在运行的程序中生效。如果发现环境变量未按预期工作，请尝试关闭并重新打开用于运行和编辑代码的任何程序。
此终结点返回的数据受各种国际法律和法规的约束，因此结果的准确性取决于多个因素。这些因素包括号码是否已转网、国家/地区代码和呼叫者的批准状态。基于上述因素，可能无法获得某些电话号码的运营商信息，或者运营商信息反映的可能是电话号码的原始运营商，而不是当前运营商。

后续步骤

在此快速入门中，你学习了如何：

查找号码格式
查找电话号码的运营商信息

号码查找概念

号码查找 SDK

通过

快速入门：了解如何使用 Azure 通信服务查找电话号码的运营商信息

先决条件

先决条件检查

设置

创建新的 Node.js 应用程序

安装包

代码示例

验证客户端

查找电话号码格式

查找号码的运营商信息

使用运营商信息

运行代码

示例代码

先决条件

先决条件检查

设置

新建 C# 应用程序

连接到开发包提要

安装包

代码示例

验证客户端

查找电话号码格式

查找号码的运营商信息

使用运营商信息

运行代码

示例代码

先决条件

先决条件检查

设置

创建新的 Java 应用程序

连接到开发包提要

安装包

代码示例

设置应用框架

验证客户端

查找电话号码格式

查找号码的运营商信息

使用运营商信息

运行代码

示例代码

先决条件

先决条件检查

设置

创建新的 Python 应用程序

安装包

代码示例

对客户端进行身份验证

查找电话号码格式

查找号码的运营商信息

使用运营商信息

运行代码

示例代码

疑难解答

后续步骤

反馈

其他资源