共用方式為


快速入門:使用 Azure 通訊服務 查閱電話號碼的操作員資訊

重要

此 Azure 通訊服務功能目前處於預覽狀態。

提供的預覽 API 並無服務等級協定。 建議您不要將其用於生產工作負載。 有些功能可能不受支援,或是在功能上有所限制。

如需詳細資訊,請參閱 Microsoft Azure 預覽版增補使用規定

開始使用適用於 JavaScript 的 電話 Numbers 用戶端連結庫,以查閱電話號碼的操作員資訊,可用來判斷是否以及如何與該電話號碼通訊。 請遵循下列步驟來安裝套件,並查閱電話號碼的操作員資訊。

注意

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

Install the package

npm install使用 命令來安裝適用於 JavaScript 的 Azure 通訊服務 電話 Numbers 用戶端連結庫。

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

選項--save會將連結庫新增為package.json檔案中的相依性。

程式碼範例

驗證用戶端

從用戶端連結庫匯入 電話 NumbersClient,並使用您的 連接字串 加以具現化,您可以從 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 ,並trueincludeAdditionalOperatorDetails傳遞 選項。

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 快速入門

執行程式碼

使用 node 命令,從終端機或命令窗口執行應用程式。

node number-lookup-quickstart.js

範例指令碼

您可以從 GitHub 下載範例應用程式

開始使用適用於 C# 的 電話 數位用戶端連結庫來查閱電話號碼的操作員資訊,這可用來判斷該電話號碼是否以及如何與該電話號碼通訊。 請遵循下列步驟來安裝套件,並查閱電話號碼的操作員資訊。

注意

在 GitHub 上尋找本快速入門的程式代碼。

必要條件

先決條件檢查

在終端機或命令視窗中,執行 dotnet 命令來檢查是否已安裝 .NET SDK。

設定

若要設定用來傳送查閱查詢的環境,請執行下列各節中的步驟。

建立新的 C# 應用程式

在終端機或命令視窗中,執行 dotnet new 命令以建立名稱為 NumberLookupQuickstart的新控制台應用程式。 此命令會建立具有單一原始程式檔的簡單 「Hello World」 C# 專案, Program.cs

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"

如需連線到開發摘要的詳細資訊和其他選項,請參閱 參與指南

Install the package

在應用程式目錄中,請使用下列命令安裝適用於 .NET 套件的 Azure 通訊服務 電話 Numbers 用戶端連結庫。

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 為異步。

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

電話 Number 用戶端也可以使用 Microsoft Entra 驗證進行驗證。 使用此選項時, AZURE_CLIENT_SECRET必須設定、 AZURE_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 ,並trueIncludeAdditionalOperatorDetails傳遞 選項。

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 快速入門

執行程式碼

使用 dotnet run 命令,從終端機或命令窗口執行應用程式。

dotnet run --interactive

範例指令碼

您可以從 GitHub 下載範例應用程式

開始使用適用於 Java 的 電話 數位用戶端連結庫來查閱電話號碼的操作員資訊,這可用來判斷該電話號碼是否以及如何與該電話號碼通訊。 請遵循下列步驟來安裝套件,並查閱電話號碼的操作員資訊。

注意

在 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 檔案是專案的 Project 物件模型或 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>

您可能需要在 中新增或編輯 settings.xml 檔案 ${user.home}/.m2

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

您可以使用封裝讀取和寫入範圍產生個人存取令牌,並將它貼到標記中<password>

如需連線到開發摘要的詳細資訊和其他選項,請參閱 這裡

Install the package

將下列相依性專案新增至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>

程式碼範例

設定應用程式架構

從專案目錄:

  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 入口網站 中的 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 ,並trueIncludeAdditionalOperatorDetails傳遞 選項。

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 快速入門

執行程式碼

使用下列命令從終端機或命令視窗執行應用程式:流覽至包含 pom.xml 檔案並編譯項目的目錄。

mvn compile

接著,建置封裝。

mvn package

若要執行應用程式,請使用 mvn 命令。

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

範例指令碼

您可以從 GitHub 下載範例應用程式

開始使用適用於 Python 的 電話 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)

Install the package

在應用程式目錄中,使用 pip install 命令安裝適用於 Python 套件的 Azure 通訊服務 電話 Numbers 用戶端連結庫。

pip install azure-communication-phonenumbers==1.2.0b2

程式碼範例

驗證用戶端

用戶端可以使用從 Azure 入口網站中的 Azure 通訊服務 資源取得的 連接字串 進行驗證。 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 物件需要您擁有 AZURE_CLIENT_IDAZURE_CLIENT_SECRET,且 AZURE_TENANT_ID 已經設定為環境變數,以及來自已註冊 Microsoft Entra 應用程式的對應值。

若要深入瞭解如何取得這些環境變數,您可以瞭解如何 從 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 ,並Trueinclude_additional_operator_details傳遞 選項。

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 快速入門

執行程式碼

使用 python 命令,從終端機或命令窗口執行應用程式。

python number_lookup_sample.py

範例指令碼

您可以從 GitHub 下載範例應用程式

疑難排解

常見問題和問題:

  • 環境變數的變更可能不會在已執行的程式中生效。 如果您注意到環境變數未如預期般運作,請嘗試關閉並重新開啟您用來執行和編輯程式代碼的任何程式。
  • 此端點傳回的數據受限於各種國際法律和法規,因此結果的正確性取決於數個因素。 這些因素包括號碼是否已移植、國家/地區代碼,以及來電者的核准狀態。 根據這些因素,操作員資訊可能無法用於某些電話號碼,或可能反映電話號碼的原始操作員,而不是目前的操作員。

下一步

在本快速入門中,您已瞭解如何:

  • 查閱數位格式設定
  • 查閱電話號碼的操作員資訊