在這個快速入門中，你將使用 Foundry Tools 中的 Azure 語言 PII 偵測功能，來識別並遮蔽文字中的個人識別資訊。 你可以使用你偏好的客戶端函式庫、REST API 或 Microsoft Foundry 入口網站開始。
如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
附註
這個快速入門指南介紹如何偵測文件中的個人識別資訊 (PII)。 要在對話中偵測 PII，請參見 「如何在對話中偵測與遮蔽 PII」。 要偵測文字中的個人身份資訊（PII），請參閱 「如何偵測與遮蔽文字中的個人身份資訊」。
參考文件 | 更多樣本 | 套件 (NuGet) | 程式庫原始程式碼
使用本快速入門，透過適用於 .NET 的用戶端程式庫，建立個人識別資訊 (PII) 偵測應用程式。 在下列範例中，您會建立 C# 應用程式，以便識別文字中辨識的敏感性資訊。
提示
你可以試試 Microsoft Foundry 平台，這樣可以不用寫程式碼就能執行 Azure 語言的任務。
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 當你擁有 Azure 訂閱後， 建立一個 Foundry 資源。
- Visual Studio IDE
設定
建立 Azure 資源
要使用下面的程式碼範例，你需要部署一個 Azure 資源。 這個資源會包含一個金鑰和端點，用來驗證你傳送到 Azure 語言的 API 呼叫。
使用下列連結，以透過 Azure 入口網站建立語言資源。 你需要用 Azure 訂閱登入。
在所出現的 [選取其他功能] 畫面上，選取 [繼續以建立您的資源]。
在 [建立語言] 畫面中，提供下列資訊：
詳細資料 描述 Subscription 與您的資源關聯的訂閱帳戶。 從下拉式功能表中選取您的 Azure 訂用帳戶。 資源群組 資源群組是一個容器，當中會儲存您所建立的資源。 選取 [新建] 來建立新的資源群組。 區域 語言資源的位置。 區域不同可能會依據您的實體位置而造成延遲，但不會影響您資源執行階段的可用性。 在本快速入門中，請選取您鄰近的可用區域，或選擇 [美國東部]。 名稱 語言資源的名稱。 此名稱也會用來建立端點 URL，供您的應用程式用來傳送 API 要求。 定價層 語言資源的定價層。 您可以使用 [免費 F0] 層來試用服務，之後可升級至付費層以用於實際執行環境。 
請確定已核取 [負責任 AI 通知] 核取方塊。
按一下頁面底部的 [檢閱 + 建立]。
在所出現的畫面中，確定驗證已通過，且您已輸入正確的資訊。 然後選擇 [建立]。
取得金鑰和端點
接下來，您將需要來自資源的金鑰與端點，以將應用程式連線至該 API。 您稍後會在快速入門中將金鑰和端點貼到程式碼中。
Azure 語言資源成功部署後，點擊「下一步步驟」下的「前往資源」按鈕。
在您的資源畫面上，選取左窗格中的[金鑰和端點]。 在下列步驟中，您將使用其中一個金鑰和端點。
建立環境變數
您的應用程式必須經過驗證後，才能傳送 API 要求。 在生產環境中，請運用安全的方式來儲存和存取您的登入資訊。 在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定語言資源金鑰的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。
- 若要設定
LANGUAGE_KEY環境變數，請將your-key取代為您資源的其中一個金鑰。 - 若要設定
LANGUAGE_ENDPOINT環境變數，請將your-endpoint取代為您資源的端點。
重要
我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。
請謹慎使用 API 金鑰。 請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。 如果使用 API 金鑰，請安全地將它們儲存在 Azure 金鑰保存庫、定期輪替金鑰，並使用角色型存取控制和網路存取限制來限制對 Azure 金鑰保存庫 的存取。 如需在應用程式中安全地使用 API 金鑰的詳細資訊，請參閱搭配 Azure 金鑰保存庫 的 API 金鑰。
如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
附註
如果您只需要存取目前執行中主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。
新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。 例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。
建立新的 .NET Core 應用程式
使用 Visual Studio IDE，建立新的 .NET Core 主控台應用程式。 此步驟建立一個「Hello World」專案，包含單一 C# 原始碼檔案： program.cs。
在 解決方案總管 中右鍵點擊解決方案，並選擇 「管理 NuGet 套件」來安裝客戶端函式庫。 在開啟的封裝管理員中，選取 [瀏覽] 並搜尋 Azure.AI.TextAnalytics。 選取版本 5.2.0，然後 安裝。 您也可以使用套件管理員主控台。
程式碼範例
將下列程式碼複製到 program.cs 檔案中，並執行該程式碼。
using Azure;
using System;
using Azure.AI.TextAnalytics;
namespace Example
{
class Program
{
// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
static string languageKey = Environment.GetEnvironmentVariable("LANGUAGE_KEY");
static string languageEndpoint = Environment.GetEnvironmentVariable("LANGUAGE_ENDPOINT");
// Example method for detecting sensitive information (PII) from text
static void RecognizePIIExample(TextAnalyticsClient client)
{
string document = "Call our office at 312-555-1234, or send an email to support@contoso.com.";
PiiEntityCollection entities = client.RecognizePiiEntities(document).Value;
Console.WriteLine($"Redacted Text: {entities.RedactedText}");
if (entities.Count > 0)
{
Console.WriteLine($"Recognized {entities.Count} PII entit{(entities.Count > 1 ? "ies" : "y")}:");
foreach (PiiEntity entity in entities)
{
Console.WriteLine($"Text: {entity.Text}, Category: {entity.Category}, SubCategory: {entity.SubCategory}, Confidence score: {entity.ConfidenceScore}");
}
}
else
{
Console.WriteLine("No entities were found.");
}
}
static void Main(string[] args)
{
if (string.IsNullOrWhiteSpace(languageKey) || string.IsNullOrWhiteSpace(languageEndpoint))
{
Console.WriteLine("Missing LANGUAGE_KEY or LANGUAGE_ENDPOINT environment variables.");
return;
}
var endpoint = new Uri(languageEndpoint);
var credentials = new AzureKeyCredential(languageKey);
var client = new TextAnalyticsClient(endpoint, credentials);
RecognizePIIExample(client);
Console.Write("Press any key to exit.");
Console.ReadKey();
}
}
}
輸出
Redacted Text: Call our office at ************, or send an email to *******************.
Recognized 2 PII entities:
Text: 312-555-1234, Category: PhoneNumber, SubCategory: , Confidence score: 0.8
Text: support@contoso.com, Category: Email, SubCategory: , Confidence score: 0.8
參考文件 | 更多樣本 | 套件 (Maven) | 程式庫原始程式碼
使用本快速入門，透過適用於 Java 的用戶端程式庫，建立個人識別資訊 (PII) 偵測應用程式。 在下列範例中，您會建立 Java 應用程式，以便識別文字中辨識的敏感性資訊。
提示
你可以試試 Microsoft Foundry 平台，這樣可以不用寫程式碼就能執行 Azure 語言的任務。
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 當你擁有 Azure 訂閱後， 建立一個 Foundry 資源。
- Java 開發套件 (JDK) 含第 8 版或更新版本
設定
建立 Azure 資源
要使用下面的程式碼範例，你需要部署一個 Azure 資源。 這個資源會包含一個金鑰和端點，用來驗證你傳送到 Azure 語言的 API 呼叫。
使用下列連結，以透過 Azure 入口網站建立語言資源。 你需要用 Azure 訂閱登入。
在所出現的 [選取其他功能] 畫面上，選取 [繼續以建立您的資源]。
在 [建立語言] 畫面中，提供下列資訊：
詳細資料 描述 Subscription 與您的資源關聯的訂閱帳戶。 從下拉式功能表中選取您的 Azure 訂用帳戶。 資源群組 資源群組是一個容器，當中會儲存您所建立的資源。 選取 [新建] 來建立新的資源群組。 區域 語言資源的位置。 區域不同可能會依據您的實體位置而造成延遲，但不會影響您資源執行階段的可用性。 在本快速入門中，請選取您鄰近的可用區域，或選擇 [美國東部]。 名稱 語言資源的名稱。 此名稱也會用來建立端點 URL，供您的應用程式用來傳送 API 要求。 定價層 語言資源的定價層。 您可以使用 [免費 F0] 層來試用服務，之後可升級至付費層以用於實際執行環境。
請確定已核取 [負責任 AI 通知] 核取方塊。
按一下頁面底部的 [檢閱 + 建立]。
在所出現的畫面中，確定驗證已通過，且您已輸入正確的資訊。 然後選擇 [建立]。
取得金鑰和端點
接下來，您將需要來自資源的金鑰與端點，以將應用程式連線至該 API。 您稍後會在快速入門中將金鑰和端點貼到程式碼中。
Azure 語言資源成功部署後，點擊「下一步步驟」下的「前往資源」按鈕。
在您的資源畫面上，選取左窗格中的[金鑰和端點]。 在下列步驟中，您將使用其中一個金鑰和端點。
建立環境變數
您的應用程式必須經過驗證後，才能傳送 API 要求。 在生產環境中，請運用安全的方式來儲存和存取您的登入資訊。 在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定語言資源金鑰的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。
- 若要設定
LANGUAGE_KEY環境變數，請將your-key取代為您資源的其中一個金鑰。 - 若要設定
LANGUAGE_ENDPOINT環境變數，請將your-endpoint取代為您資源的端點。
重要
我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。
請謹慎使用 API 金鑰。 請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。 如果使用 API 金鑰，請安全地將它們儲存在 Azure 金鑰保存庫、定期輪替金鑰，並使用角色型存取控制和網路存取限制來限制對 Azure 金鑰保存庫 的存取。 如需在應用程式中安全地使用 API 金鑰的詳細資訊，請參閱搭配 Azure 金鑰保存庫 的 API 金鑰。
如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
附註
如果您只需要存取目前執行中主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。
新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。 例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。
新增 用戶端程式庫
在您慣用的 IDE 或開發環境中建立 Maven 專案。 然後，在專案的 pom.xml 檔案中新增下列相依性。 您可以在線上找到其他建置工具的實作語法。
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-textanalytics</artifactId>
<version>5.2.0</version>
</dependency>
</dependencies>
程式碼範例
建立名為 Example.java 的 Java 檔案。 打開檔案並複製以下程式碼。 然後執行程式碼。
import com.azure.core.credential.AzureKeyCredential;
import com.azure.ai.textanalytics.models.*;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.TextAnalyticsClient;
public class Example {
// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
private static String languageKey = System.getenv("LANGUAGE_KEY");
private static String languageEndpoint = System.getenv("LANGUAGE_ENDPOINT");
public static void main(String[] args) {
if (languageKey == null || languageKey.isBlank() || languageEndpoint == null || languageEndpoint.isBlank()) {
throw new IllegalArgumentException("Missing LANGUAGE_KEY or LANGUAGE_ENDPOINT environment variables");
}
TextAnalyticsClient client = authenticateClient(languageKey, languageEndpoint);
recognizePiiEntitiesExample(client);
}
// Method to authenticate the client object with your key and endpoint
static TextAnalyticsClient authenticateClient(String key, String endpoint) {
return new TextAnalyticsClientBuilder()
.credential(new AzureKeyCredential(key))
.endpoint(endpoint)
.buildClient();
}
// Example method for detecting sensitive information (PII) from text
static void recognizePiiEntitiesExample(TextAnalyticsClient client)
{
// The text that need be analyzed.
String document = "My SSN is 859-98-0987";
PiiEntityCollection piiEntityCollection = client.recognizePiiEntities(document);
System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
piiEntityCollection.forEach(entity -> System.out.printf(
"Recognized Personally Identifiable Information entity: %s, entity category: %s, entity subcategory: %s,"
+ " confidence score: %f.%n",
entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));
}
}
輸出
Redacted Text: My SSN is ***********
Recognized Personally Identifiable Information entity: 859-98-0987, entity category: USSocialSecurityNumber, entity subcategory: null, confidence score: 0.650000.
參考文件 | 更多樣本 | 套件 (npm) | 程式庫原始程式碼
使用本快速入門，透過適用於 Node.js 的用戶端程式庫，建立個人識別資訊 (PII) 偵測應用程式。 在下列範例中，您會建立 JavaScript 應用程式，以便識別文字中辨識的敏感性資訊。
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 當你擁有 Azure 訂閱後， 建立一個 Foundry 資源。
-
Node.js v14
LTS或更新版本
設定
建立 Azure 資源
要使用下面的程式碼範例，你需要部署一個 Azure 資源。 這個資源會包含一個金鑰和端點，用來驗證你傳送到 Azure 語言的 API 呼叫。
使用下列連結，以透過 Azure 入口網站建立語言資源。 你需要用 Azure 訂閱登入。
在所出現的 [選取其他功能] 畫面上，選取 [繼續以建立您的資源]。
在 [建立語言] 畫面中，提供下列資訊：
詳細資料 描述 Subscription 與您的資源關聯的訂閱帳戶。 從下拉式功能表中選取您的 Azure 訂用帳戶。 資源群組 資源群組是一個容器，當中會儲存您所建立的資源。 選取 [新建] 來建立新的資源群組。 區域 語言資源的位置。 區域不同可能會依據您的實體位置而造成延遲，但不會影響您資源執行階段的可用性。 在本快速入門中，請選取您鄰近的可用區域，或選擇 [美國東部]。 名稱 語言資源的名稱。 此名稱也會用來建立端點 URL，供您的應用程式用來傳送 API 要求。 定價層 語言資源的定價層。 您可以使用 [免費 F0] 層來試用服務，之後可升級至付費層以用於實際執行環境。
請確定已核取 [負責任 AI 通知] 核取方塊。
按一下頁面底部的 [檢閱 + 建立]。
在所出現的畫面中，確定驗證已通過，且您已輸入正確的資訊。 然後選擇 [建立]。
取得金鑰和端點
接下來，您將需要來自資源的金鑰與端點，以將應用程式連線至該 API。 您稍後會在快速入門中將金鑰和端點貼到程式碼中。
Azure 語言資源成功部署後，點擊「下一步步驟」下的「前往資源」按鈕。
在您的資源畫面上，選取左窗格中的[金鑰和端點]。 在下列步驟中，您將使用其中一個金鑰和端點。
建立環境變數
您的應用程式必須經過驗證後，才能傳送 API 要求。 在生產環境中，請運用安全的方式來儲存和存取您的登入資訊。 在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定語言資源金鑰的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。
- 若要設定
LANGUAGE_KEY環境變數，請將your-key取代為您資源的其中一個金鑰。 - 若要設定
LANGUAGE_ENDPOINT環境變數，請將your-endpoint取代為您資源的端點。
重要
我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。
請謹慎使用 API 金鑰。 請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。 如果使用 API 金鑰，請安全地將它們儲存在 Azure 金鑰保存庫、定期輪替金鑰，並使用角色型存取控制和網路存取限制來限制對 Azure 金鑰保存庫 的存取。 如需在應用程式中安全地使用 API 金鑰的詳細資訊，請參閱搭配 Azure 金鑰保存庫 的 API 金鑰。
如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
附註
如果您只需要存取目前執行中主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。
新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。 例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。
建立新的 Node.js 應用程式
在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為您的應用程式建立新的目錄，並瀏覽至該目錄。
mkdir myapp
cd myapp
執行命令 npm init，以使用 package.json 檔案建立節點應用程式。
npm init
安裝用戶端程式庫
安裝 npm 套件：
npm install @azure/ai-text-analytics
程式碼範例
打開檔案並複製以下範例並執行程式碼。
"use strict";
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
const key = process.env.LANGUAGE_KEY;
const endpoint = process.env.LANGUAGE_ENDPOINT;
if (!key || !endpoint) {
throw new Error("Missing LANGUAGE_KEY or LANGUAGE_ENDPOINT environment variables.");
}
async function main() {
console.log(`PII recognition sample`);
const client = new TextAnalyticsClient(endpoint, new AzureKeyCredential(key));
const documents = ["My phone number is 555-555-5555"];
const results = await client.recognizePiiEntities(documents, "en");
for (const result of results) {
if (result.error) {
console.error("Encountered an error:", result.error);
continue;
}
console.log(`Redacted text: "${result.redactedText}"`);
console.log("PII entities:");
for (const entity of result.entities) {
console.log(`\t- "${entity.text}" of type ${entity.category}`);
}
}
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
輸出
PII recognition sample
Redacted text: "My phone number is ************"
PII entities:
- "555-555-5555" of type PhoneNumber
參考文件 | 更多樣本 | 套件 (PyPi) | 程式庫原始程式碼
使用本快速入門，透過適用於 Python 的用戶端程式庫，建立個人識別資訊 (PII) 偵測應用程式。 在下列範例中，您會建立 Python 應用程式，以便識別文字中辨識的敏感性資訊。
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 當你擁有 Azure 訂閱後， 建立一個 Foundry 資源。
- Python 3.8 或更新版本
設定
建立 Azure 資源
要使用下面的程式碼範例，你需要部署一個 Azure 資源。 這個資源會包含一個金鑰和端點，用來驗證你傳送到 Azure 語言的 API 呼叫。
使用下列連結，以透過 Azure 入口網站建立語言資源。 你需要用 Azure 訂閱登入。
在所出現的 [選取其他功能] 畫面上，選取 [繼續以建立您的資源]。
在 [建立語言] 畫面中，提供下列資訊：
詳細資料 描述 Subscription 與您的資源關聯的訂閱帳戶。 從下拉式功能表中選取您的 Azure 訂用帳戶。 資源群組 資源群組是一個容器，當中會儲存您所建立的資源。 選取 [新建] 來建立新的資源群組。 區域 語言資源的位置。 區域不同可能會依據您的實體位置而造成延遲，但不會影響您資源執行階段的可用性。 在本快速入門中，請選取您鄰近的可用區域，或選擇 [美國東部]。 名稱 語言資源的名稱。 此名稱也會用來建立端點 URL，供您的應用程式用來傳送 API 要求。 定價層 語言資源的定價層。 您可以使用 [免費 F0] 層來試用服務，之後可升級至付費層以用於實際執行環境。
請確定已核取 [負責任 AI 通知] 核取方塊。
按一下頁面底部的 [檢閱 + 建立]。
在所出現的畫面中，確定驗證已通過，且您已輸入正確的資訊。 然後選擇 [建立]。
取得金鑰和端點
接下來，您將需要來自資源的金鑰與端點，以將應用程式連線至該 API。 您稍後會在快速入門中將金鑰和端點貼到程式碼中。
Azure 語言資源成功部署後，點擊「下一步步驟」下的「前往資源」按鈕。
在您的資源畫面上，選取左窗格中的[金鑰和端點]。 在下列步驟中，您將使用其中一個金鑰和端點。
建立環境變數
您的應用程式必須經過驗證後，才能傳送 API 要求。 在生產環境中，請運用安全的方式來儲存和存取您的登入資訊。 在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定語言資源金鑰的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。
- 若要設定
LANGUAGE_KEY環境變數，請將your-key取代為您資源的其中一個金鑰。 - 若要設定
LANGUAGE_ENDPOINT環境變數，請將your-endpoint取代為您資源的端點。
重要
我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。
請謹慎使用 API 金鑰。 請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。 如果使用 API 金鑰，請安全地將它們儲存在 Azure 金鑰保存庫、定期輪替金鑰，並使用角色型存取控制和網路存取限制來限制對 Azure 金鑰保存庫 的存取。 如需在應用程式中安全地使用 API 金鑰的詳細資訊，請參閱搭配 Azure 金鑰保存庫 的 API 金鑰。
如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
附註
如果您只需要存取目前執行中主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。
新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。 例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。
安裝用戶端程式庫
安裝 Python 之後，您可以透過以下項目安裝用戶端程式庫：
pip install azure-ai-textanalytics==5.2.0
程式碼範例
建立新的 Python 檔案，並複製下列程式碼。 然後執行程式碼。
import os
from azure.ai.textanalytics import TextAnalyticsClient
from azure.core.credentials import AzureKeyCredential
# This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
language_key = os.environ.get("LANGUAGE_KEY")
language_endpoint = os.environ.get("LANGUAGE_ENDPOINT")
if not language_key or not language_endpoint:
raise ValueError("Missing LANGUAGE_KEY or LANGUAGE_ENDPOINT environment variables")
# Authenticate the client using your key and endpoint
def authenticate_client():
ta_credential = AzureKeyCredential(language_key)
text_analytics_client = TextAnalyticsClient(
endpoint=language_endpoint,
credential=ta_credential)
return text_analytics_client
client = authenticate_client()
# Example method for detecting sensitive information (PII) from text
def pii_recognition_example(client):
documents = [
"The employee's SSN is 859-98-0987.",
"The employee's phone number is 555-555-5555."
]
response = client.recognize_pii_entities(documents, language="en")
result = [doc for doc in response if not doc.is_error]
for doc in result:
print("Redacted Text: {}".format(doc.redacted_text))
for entity in doc.entities:
print("Entity: {}".format(entity.text))
print("\tCategory: {}".format(entity.category))
print("\tConfidence Score: {}".format(entity.confidence_score))
print("\tOffset: {}".format(entity.offset))
print("\tLength: {}".format(entity.length))
pii_recognition_example(client)
輸出
Redacted Text: The ********'s SSN is ***********.
Entity: employee
Category: PersonType
Confidence Score: 0.97
Offset: 4
Length: 8
Entity: 859-98-0987
Category: USSocialSecurityNumber
Confidence Score: 0.65
Offset: 22
Length: 11
Redacted Text: The ********'s phone number is ************.
Entity: employee
Category: PersonType
Confidence Score: 0.96
Offset: 4
Length: 8
Entity: 555-555-5555
Category: PhoneNumber
Confidence Score: 0.8
Offset: 31
Length: 12
使用本快速入門，利用 REST API 傳送個人識別資訊 (PII) 偵測請求。 在下列範例中，您將使用 cURL 來識別文字中已辨識的敏感性資訊。
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 當你擁有 Azure 訂閱後， 建立一個 Foundry 資源。
設定
建立 Azure 資源
要使用下面的程式碼範例，你需要部署一個 Azure 資源。 這個資源會包含一個金鑰和端點，用來驗證你傳送到 Azure 語言的 API 呼叫。
使用下列連結，以透過 Azure 入口網站建立語言資源。 你需要用 Azure 訂閱登入。
在所出現的 [選取其他功能] 畫面上，選取 [繼續以建立您的資源]。
在 [建立語言] 畫面中，提供下列資訊：
詳細資料 描述 Subscription 與您的資源關聯的訂閱帳戶。 從下拉式功能表中選取您的 Azure 訂用帳戶。 資源群組 資源群組是一個容器，當中會儲存您所建立的資源。 選取 [新建] 來建立新的資源群組。 區域 語言資源的位置。 區域不同可能會依據您的實體位置而造成延遲，但不會影響您資源執行階段的可用性。 在本快速入門中，請選取您鄰近的可用區域，或選擇 [美國東部]。 名稱 語言資源的名稱。 此名稱也會用來建立端點 URL，供您的應用程式用來傳送 API 要求。 定價層 語言資源的定價層。 您可以使用 [免費 F0] 層來試用服務，之後可升級至付費層以用於實際執行環境。
請確定已核取 [負責任 AI 通知] 核取方塊。
按一下頁面底部的 [檢閱 + 建立]。
在所出現的畫面中，確定驗證已通過，且您已輸入正確的資訊。 然後選擇 [建立]。
取得金鑰和端點
接下來，您將需要來自資源的金鑰與端點，以將應用程式連線至該 API。 您稍後會在快速入門中將金鑰和端點貼到程式碼中。
Azure 語言資源成功部署後，點擊「下一步步驟」下的「前往資源」按鈕。
在您的資源畫面上，選取左窗格中的[金鑰和端點]。 在下列步驟中，您將使用其中一個金鑰和端點。
建立環境變數
您的應用程式必須經過驗證後，才能傳送 API 要求。 在生產環境中，請運用安全的方式來儲存和存取您的登入資訊。 在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定語言資源金鑰的環境變數，請開啟主控台視窗，並遵循作業系統和開發環境的指示進行。
- 若要設定
LANGUAGE_KEY環境變數，請將your-key取代為您資源的其中一個金鑰。 - 若要設定
LANGUAGE_ENDPOINT環境變數，請將your-endpoint取代為您資源的端點。
重要
我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。
請謹慎使用 API 金鑰。 請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。 如果使用 API 金鑰，請安全地將它們儲存在 Azure 金鑰保存庫、定期輪替金鑰，並使用角色型存取控制和網路存取限制來限制對 Azure 金鑰保存庫 的存取。 如需在應用程式中安全地使用 API 金鑰的詳細資訊，請參閱搭配 Azure 金鑰保存庫 的 API 金鑰。
如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
附註
如果您只需要存取目前執行中主控台的環境變數，您可以使用 set (而不是 setx) 來設定環境變數。
新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。 例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。
使用範例請求本體來建立 JSON 檔案
在程式碼編輯器中，建立名為 test_pii_payload.json 的新檔案，並複製下列 JSON 範例。 在下一個步驟中，會將此範例要求傳送至 API。
{
"kind": "PiiEntityRecognition",
"parameters": {
"modelVersion": "latest"
},
"analysisInput":{
"documents":[
{
"id":"1",
"language": "en",
"text": "Call our office at 312-555-1234, or send an email to support@contoso.com"
}
]
}
}
將 test_pii_payload.json 儲存在電腦上的某個位置。 例如，您的桌面。
傳送個人識別資訊 (PII) 偵測 API 要求
使用下列命令，透過您正在使用的程式來傳送 API 要求。 將命令複製到終端機，然後執行該命令。
| 參數 | 描述 |
|---|---|
-X POST <endpoint> |
指定用於存取 API 的端點。 |
-H Content-Type: application/json |
用於傳送 JSON 資料的內容類型。 |
-H "Ocp-Apim-Subscription-Key: <key>" |
指定用於存取 API 的金鑰。 |
-d <documents> |
JSON，其中包含您想要傳送的文件。 |
將 C:\Users\<myaccount>\Desktop\test_pii_payload.json 替換為您在上一個步驟中建立的範例 JSON 請求檔案的路徑。
命令提示字元
curl -X POST "%LANGUAGE_ENDPOINT%/language/:analyze-text?api-version=2022-05-01" ^
-H "Content-Type: application/json" ^
-H "Ocp-Apim-Subscription-Key: %LANGUAGE_KEY%" ^
-d "@C:\Users\<myaccount>\Desktop\test_pii_payload.json"
PowerShell
curl.exe -X POST $env:LANGUAGE_ENDPOINT/language/:analyze-text?api-version=2022-05-01 `
-H "Content-Type: application/json" `
-H "Ocp-Apim-Subscription-Key: $env:LANGUAGE_KEY" `
-d "@C:\Users\<myaccount>\Desktop\test_pii_payload.json"
JSON 回應
{
"kind": "PiiEntityRecognitionResults",
"results": {
"documents": [{
"redactedText": "Call our office at ************, or send an email to *******************",
"id": "1",
"entities": [{
"text": "312-555-1234",
"category": "PhoneNumber",
"offset": 19,
"length": 12,
"confidenceScore": 0.8
}, {
"text": "support@contoso.com",
"category": "Email",
"offset": 53,
"length": 19,
"confidenceScore": 0.8
}],
"warnings": []
}],
"errors": [],
"modelVersion": "2021-01-15"
}
}
必要條件
提示
- 如果你已經在 Foundry 工具中使用了 Azure 語言或多服務資源——無論是單獨使用還是透過 Language Studio 使用——你都可以繼續在 Microsoft Foundry 入口網站中使用這些現有的語言資源。
- 欲了解更多資訊，請參閱 Microsoft Foundry 入口網站中的 Connect 服務。
- 考慮使用 Foundry 資源以獲得最佳體驗。 你也可以使用語言資源來依照這些指示。
- Azure 訂用帳戶。 如果您沒有帳戶，您可以 免費建立一個。
- 必要許可權。 請確定建立帳戶和項目的人員已獲指派為訂用帳戶層級的 Azure AI 帳戶擁有者角色。 或者，在訂用帳戶範圍擁有 [參與者] 或 [認知服務參與者] 角色也符合這項需求。 欲了解更多資訊，請參閱基於角色的存取控制（RBAC）。
- Foundry 資源。 建立 一個 Foundry 資源 ，或參見 「配置 Foundry 資源」。 或者，你也可以使用 語言資源。
- 一個鑄造廠的專案。 欲了解更多資訊，請參閱 「建立鑄造廠專案」。
附註
本內容指的是 Foundry (傳統版) 入口網站，支援樞紐型專案及其他資源類型。 要確認你使用的是 Foundry（經典版），請確保傳送門橫幅中的版本切換設定在 關閉 位置。 
你可以使用 Foundry（經典版） 來：
- 從對話中擷取個人識別資訊（PII）
- 從文字擷取 PII
- 設定編輯策略
- 檢視偵測到的實體與信心分數
前往鑄造廠（經典）遊樂場導航
- 在左窗格中，選取 [Playgrounds]。
- 選擇 「嘗試 Azure 語言 Playground 」按鈕。
在鑄造廠遊樂場偵測 PII
語言 遊樂場 包含四個區段：
| 章節 | 目標 |
|---|---|
| 頂部橫幅 | 選擇輸入語言並選擇個人識別資訊（PII）偵測能力。 |
| 左側窗格 | 設定 配置 選項，如 API 版本、模型版本及編輯政策。 |
| 中央玻璃 | 輸入文字進行處理並檢視標註結果。 |
| 右側面板 | 查看每個偵測到的實體 的詳細資訊 。 |
從頂方橫幅圖塊中選擇 「從對話中擷取 PII 」或「 從文字中擷取 PII 」。 每種能力針對不同的情境。
從交談擷取個人識別資訊（PII）
從交談擷取 PII 旨在識別和遮蔽交談文字中的個人識別資訊。
在 [ 設定 ] 中，有下列選項：
| 選項 | 描述 |
|---|---|
| 選取 API 版本 | 選取要使用的 API 版本。 |
| 選取模型版本 | 選取要使用的模型版本。 |
| 選取文字語言 | 選擇輸入文字的語言。 |
| 選取要包含的類型 | 選擇你想遮蔽的資訊類型。 |
| 指定修訂原則 | 選取修訂方法。 |
| 指定修訂字元 | 選擇用於編輯的字元。 僅適用於 CharacterMask 修訂原則。 |
操作完成後，每個偵測到的實體會在中央窗格中被高亮顯示，並顯示其類型標籤。
詳細資訊區塊包含每個實體的以下欄位：
| 欄位 | 描述 |
|---|---|
| 實體 | 偵測到的實體。 |
| 類別 | 偵測到的實體類型。 |
| Offset | 從該行開頭到該實體的字元數。 |
| 長度 | 實體的字元長度。 |
| 信賴度 | 模型對實體類型正確性的確定程度。 |
在 Foundry 入口網站的右側窗格中，一張截圖顯示會話中標示出的偵測到的 PII 實體，並且其實體詳情亦有顯示。
請確認每個 PII 實體是否以正確的分類標籤標示出來。 若無實體，請檢查輸入文字是否包含可辨識的個人識別資訊（PII）模式，且 類型過濾器是否 包含預期的類別。
從文字擷取 PII
從文字 擷取 PII 是設計來識別和遮罩文字中個人標識資訊。
在 設定 中，您可以從以下選項中選擇：
| 選項 | 描述 |
|---|---|
| 選取 API 版本 | 選取要使用的 API 版本。 |
| 選取模型版本 | 選取要使用的模型版本。 |
| 選取文字語言 | 選擇輸入文字的語言。 |
| 選取要包含的類型 | 選擇你想遮蔽的資訊類型。 |
| 指定修訂原則 | 選取修訂方法。 |
| 指定修訂字元 | 選擇用於編輯的字元。 僅適用於 CharacterMask 修訂原則。 |
操作完成後，每個偵測到的實體會在中央窗格中被高亮顯示，並顯示其類型標籤。
詳細資訊區塊包含每個實體的以下欄位：
| 欄位 | 描述 |
|---|---|
| 實體 | 偵測到的實體。 |
| 類別 | 偵測到的實體類型。 |
| Offset | 從該行開頭到該實體的字元數。 |
| 長度 | 實體的字元長度。 |
| 信賴度 | 模型對實體類型正確性的確定程度。 |
| 標籤 | 模型對每個已識別實體子類型的置信度分數。 |
請確認每個 PII 實體是否以正確的分類標籤標示出來。 標籤欄 顯示子類別的信心分數（若適用）。
故障排除
| 問題 | 解決辦法 |
|---|---|
呼叫 API 時會收到 401 or 403 錯誤。 |
請確認您的金鑰和端點是否正確，以便匹配同一個 Azure AI 資源。 如果你最近換了角色，請等幾分鐘再試一次。 |
| 你會收到關於缺少環境變數的錯誤訊息。 | 在你執行樣本前，先確認 LANGUAGE_KEY 並 LANGUAGE_ENDPOINT 設定在你的環境中。 |
| Foundry 的使用體驗與操作步驟不符。 | 在 Foundry 入口網站中，使用版本切換來在 Foundry (classic) 與 Foundry (new) 之間切換，然後依照 Foundry 區段中的對應分頁操作。 |
| 你的文字中沒有偵測到任何實體。 | 確認輸入文字包含可辨識的個人資訊（PII）模式（姓名、地址、電話號碼）。 請檢查 Types 篩選器是否包含您預期的實體類別。 |
API 會回傳錯誤 InvalidLanguage 。 |
請確認請求中的語言代碼 是否符合支援的語言之一。 |
清除資源
如果你不再需要在這個快速入門中建立的資源，請刪除個別資源或整個資源群組。 刪除資源群組也會刪除所有與之相關的其他資源。