快速入門:使用 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
,並true
includeAdditionalOperatorDetails
傳遞 選項。
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 上尋找本快速入門的程式代碼。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 適用於您作業系統的 最新版本 .NET Core 用戶端連結庫 。
- 作用中的通訊服務資源和 連接字串。 建立通訊服務資源。
先決條件檢查
在終端機或命令視窗中,執行 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_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
,並true
IncludeAdditionalOperatorDetails
傳遞 選項。
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 上尋找本快速入門的程式代碼。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- Java Development Kit (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
'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>
程式碼範例
設定應用程式架構
從專案目錄:
- 流覽至 /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
,並true
IncludeAdditionalOperatorDetails
傳遞 選項。
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 上尋找本快速入門的程式代碼。
必要條件
- 具有有效訂用帳戶的 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)
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_ID
、 AZURE_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
,並True
include_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 下載範例應用程式。
疑難排解
常見問題和問題:
- 環境變數的變更可能不會在已執行的程式中生效。 如果您注意到環境變數未如預期般運作,請嘗試關閉並重新開啟您用來執行和編輯程式代碼的任何程式。
- 此端點傳回的數據受限於各種國際法律和法規,因此結果的正確性取決於數個因素。 這些因素包括號碼是否已移植、國家/地區代碼,以及來電者的核准狀態。 根據這些因素,操作員資訊可能無法用於某些電話號碼,或可能反映電話號碼的原始操作員,而不是目前的操作員。
下一步
在本快速入門中,您已瞭解如何:
- 查閱數位格式設定
- 查閱電話號碼的操作員資訊