SDK 目標：REST API v2.1 (GA)

REST API 版本 v2.1 (GA) 21-06-08

Azure AI 文件智慧服務是一項雲端服務，會使用機器學習來分析文件中的文字和結構化資料。 文件智慧軟體開發套件 (SDK) 是一組程式庫和工具，可讓您輕鬆地將文件智慧模型和功能整合到應用程式中。 可跨平台使用 C#/.NET、Java、JavaScript 和 Python 程式設計語言，來使用文件智慧 SDK。

支援的程式設計語言

文件智慧 SDK 支援下列語言和平台：

語言 → 文件智慧 SDK 版本	套件	支援的 API 版本	平台支援
.NET/C# → 3.1.x (GA)	NuGet (英文)	v2.1	Windows、macOS、Linux、Docker
Java → 3.1.x (GA)	Maven 存放庫	v2.1	Windows、macOS、Linux
JavaScript → 3.1.0 (GA)	npm \(英文\)	v2.1	瀏覽器、Windows、macOS、Linux
Python → 3.1.0 (GA)	PyPI	v2.1
Windows、macOS、Linux

如需其他 SDK 版本的相關資訊，請參閱：

• 2024-02-29 (預覽)
• 2023-07-31 v3.1 (GA)
• 2022-08-31 v3.0 (GA)

支援的用戶端

語言	SDK 版本	API 版本	支援的用戶端
.NET/C# JAVA JavaScript	3.1.x	v2.1 (預設) v2.0	FormRecognizerClient FormTrainingClient
.NET/C# JAVA JavaScript	3.0.x	v2.0	FormRecognizerClient FormTrainingClient
Python	3.1.x	v2.1 (預設) v2.0	FormRecognizerClient FormTrainingClient
Python	3.0.0	v2.0	FormRecognizerClient FormTrainingClient

在應用程式中使用文件智慧 SDK

文件智慧 SDK 讓您能夠在應用程式中使用和管理文件智慧服務。 SDK 建置於基礎文件智慧 REST API 上，可讓您輕鬆地在程式設計語言範例內使用這些 API。 以下說明如何使用您慣用語言的文件智慧 SDK：

1.安裝 SDK 用戶端程式庫

C#/.NET

dotnet add package Azure.AI.FormRecognizer --version 3.1.0

Install-Package Azure.AI.FormRecognizer -Version 3.1.0

Java

<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-formrecognizer</artifactId>
<version>3.1.0</version>
</dependency>

implementation("com.azure:azure-ai-formrecognizer:3.1.0")

JavaScript

npm i @azure/ai-form-recognizer@3.1.0

Python

pip install azure-ai-formrecognizer==3.1.0

2.將 SDK 用戶端程式庫匯入您的應用程式中

C#/.NET

using Azure;
using Azure.AI.FormRecognizer.Models;

Java

import com.azure.ai.formrecognizer.*;
import com.azure.ai.formrecognizer.models.*;

import com.azure.core.credential.AzureKeyCredential;

JavaScript

const { FormRecognizerClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");

Python

    from azure.ai.formrecognizer import FormRecognizerClient
    from azure.core.credentials import AzureKeyCredential

3.設定驗證

有兩種支援的驗證方法。

• 使用文件智慧 API 金鑰搭配 azure.core.credentials 中的 AzureKeyCredential。

• 使用來自 azure-identity 的權杖認證搭配 Microsoft Entra ID 進行驗證。

使用您的 API 金鑰

您可以在 Azure 入口網站中的下列位置找到文件智慧 API 金鑰：

重要

我們建議使用適用於 Azure 資源的受控識別搭配 Microsoft Entra ID 驗證，以避免使用在雲端執行的應用程式儲存認證。

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求。

C#/.NET

//set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal to create your `AzureKeyCredential` and `FormRecognizerClient` instance
  string key = "<your-key>";
  string endpoint = "<your-endpoint>";
  FormRecognizerClient client = new FormRecognizerClient(new Uri(endpoint), new AzureKeyCredential(key));

Java

// create your `FormRecognizerClient` instance and `AzureKeyCredential` variable
FormRecognizerClient formRecognizerClient = new FormRecognizerClientBuilder()
     .credential(new AzureKeyCredential("<your-key>"))
     .endpoint("<your-endpoint>")
     .buildClient();

JavaScript

// create your `FormRecognizerClient` instance and `AzureKeyCredential` variable
async function main() {
    const client = new FormRecognizerClient("<your-endpoint>", new AzureKeyCredential("<your-key>"));

Python

# create your `FormRecognizerClient` instance and `AzureKeyCredential` variable
    form_recognizer_client = FormRecognizerClient(endpoint="<your-endpoint>", credential=AzureKeyCredential("<your-key>"))

使用 Microsoft Entra 權杖認證

注意

區域端點不支援 Microsoft Entra 驗證。 為您的資源建立自訂子網域，以使用此類型的驗證。

使用 DefaultAzureCredential 是最簡單的授權方式。 它會根據執行中的環境提供預設權杖認證，足以因應多數 Azure 驗證案例的需求。

C#/.NET

以下說明如何取得和使用 .NET 應用程式的 DefaultAzureCredential：

1. 安裝適用於 .NET 的 Azure 身分識別程式庫：

       dotnet add package Azure.Identity
   

       Install-Package Azure.Identity
   

2. 註冊 Microsoft Entra 應用程式並建立新的服務主體。

3. 將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。

4. 將 Microsoft Entra 應用程式中用戶端識別碼、租用戶識別碼和用戶端密碼的值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

5. 建立您的 FormRecognizerClient 執行個體，包括 DefaultAzureCredential：

   string endpoint = "<your-endpoint>";
   var client = new FormRecognizerClient(new Uri(endpoint), new DefaultAzureCredential());
   

如需詳細資訊，請參閱驗證用戶端。

Java

以下說明如何取得和使用 Java 應用程式的 DefaultAzureCredential：

1. 安裝適用於 Java 的 Azure 身分識別程式庫：

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

2. 註冊 Microsoft Entra 應用程式並建立新的服務主體。

3. 將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。

4. 將 Microsoft Entra 應用程式的用戶端識別碼、租用戶識別碼和用戶端密碼值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

5. 建立您的 FormRecognizerClient 執行個體和 TokenCredential 變數：

   TokenCredential credential = new DefaultAzureCredentialBuilder().build();
   FormRecognizerClient formRecognizerClient = new FormRecognizerClientBuilder()
       .endpoint("{your-endpoint}")
       .credential(credential)
       .buildClient();
   

如需詳細資訊，請參閱驗證用戶端。

JavaScript

以下說明如何取得和使用 JavaScript 應用程式的 DefaultAzureCredential：

1. 安裝適用於 JavaScript 的 Azure 身分識別程式庫：

   npm install @azure/identity
   

2. 註冊 Microsoft Entra 應用程式並建立新的服務主體。

3. 將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。

4. 將 Microsoft Entra 應用程式的用戶端識別碼、租用戶識別碼和用戶端密碼值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

5. 建立您的 FormRecognizerClient 執行個體，包括 DefaultAzureCredential：

   const { FormRecognizerClient } = require("@azure/ai-form-recognizer");
   const { DefaultAzureCredential } = require("@azure/identity");
   
   const client = new FormRecognizerClient("<your-endpoint>", new DefaultAzureCredential());
   

如需詳細資訊，請參閱建立和驗證用戶端。

Python

以下說明如何取得和使用 Python 應用程式的 DefaultAzureCredential。

1. 安裝適用於 Python 的 Azure 身分識別程式庫：

   pip install azure-identity
   

2. 註冊 Microsoft Entra 應用程式並建立新的服務主體。

3. 將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。

4. 將 Microsoft Entra 應用程式的用戶端識別碼、租用戶識別碼和用戶端密碼值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

5. 建立您的 FormRecognizerClient 執行個體，包括 DefaultAzureCredential：

   from azure.identity import DefaultAzureCredential
   from azure.ai.formrecognizer import FormRecognizerClient
   
   credential = DefaultAzureCredential()
   form_recognizer_client = FormRecognizerClient(
       endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",
       credential=credential
   )
   

如需詳細資訊，請參閱驗證用戶端。

4.建置應用程式

建立用戶端物件以與文件智慧 SDK 互動，然後在該用戶端物件上呼叫與服務互動的方法。 SDK 同時提供同步和非同步方法。 如需詳細資訊，請根據您選擇的語言嘗試進行快速入門。

說明選項

Microsoft Q & A 和 Stack Overflow 論壇可供開發人員社群用來詢問和回答有關 Azure AI 文件智慧服務及其他服務的問題。 Microsoft 會監視論壇，並回覆社群尚未回答的問題。 若要確保我們會看到您的問題，請使用 azure-form-recognizer 加以標記。

下一步

探索文件智慧服務 REST API v2.1

試用文件智慧快速入門