SDK 目標：REST API 2023-07-31 (GA)

文章
10/16/2024

REST API 版本 2023-07-31 (GA)

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

支援的程式設計語言

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

語言 → 文件智慧服務 SDK 版本	套件	支援的 API 版本	平台支援
.NET/C# → 最新版 (GA)	NuGet (英文)	2023-07-31 (GA)
Java → 最新版 (GA)	Maven 存放庫	2023-07-31 (GA)	Windows、macOS、Linux
JavaScript → 最新版 (GA)	npm \(英文\)	2023-07-31 (GA)	瀏覽器、Windows、macOS、Linux
Python → 最新版 (GA)	PyPI	2023-07-31 (GA)	Windows、macOS、Linux

如需其他 SDK 版本的詳細資訊，請參閱：

支援的用戶端

下表顯示每個 SDK 版本與文件智慧服務支援的 API 版本之間的相互關聯。

語言	SDK 版本	API 版本 (預設)	支援的用戶端
.NET/C# 4.1.0	v3.1 最新版 (GA)	2023-07-31	DocumentAnalysisClient DocumentModelAdministrationClient
.NET/C# 4.0.0	v3.0 (GA)	2022-08-31	DocumentAnalysisClient DocumentModelAdministrationClient
.NET/C# 3.1.x	v2.1	v2.1	FormRecognizerClient FormTrainingClient
.NET/C# 3.0.x	v2.0	v2.0	FormRecognizerClient FormTrainingClient

語言	SDK 版本	API 版本	支援的用戶端
Java 4.1.0	v3.1 最新版 (GA)	2023-07-31 (預設)	DocumentAnalysisClient DocumentModelAdministrationClient
Java 4.0.0	v3.0 (GA)	2022-08-31	DocumentAnalysisClient DocumentModelAdministrationClient
Java 3.1.x	v2.1	v2.1	FormRecognizerClient FormTrainingClient
Java 3.0.x	v2.0	v2.0	FormRecognizerClient FormTrainingClient

語言	SDK 版本	API 版本 (預設)	支援的用戶端
JavaScript 5.0.0	v3.1 最新版 (GA)	2023-07-31 (預設)	DocumentAnalysisClient DocumentModelAdministrationClient
JavaScript 4.0.0	v3.0 (GA)	2022-08-31	DocumentAnalysisClient DocumentModelAdministrationClient
JavaScript 3.1.x	v2.1	v2.1	FormRecognizerClient FormTrainingClient
JavaScript 3.0.x	v2.0	v2.0	FormRecognizerClient FormTrainingClient

語言	SDK 版本	API 版本 (預設)	支援的用戶端
Python 3.3.0	v3.1 最新版 (GA)	2023-07-31 (預設)	DocumentAnalysisClient DocumentModelAdministrationClient
Python 3.2.x	v3.0 (GA)	2022-08-31	DocumentAnalysisClient DocumentModelAdministrationClient
Python 3.1.x	v2.1	v2.1	FormRecognizerClient FormTrainingClient
Python 3.0.0	v2.0	v2.0	FormRecognizerClient FormTrainingClient

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

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

1.安裝 SDK 用戶端程式庫

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

Install-Package Azure.AI.FormRecognizer -Version 4.1.0

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

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

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

pip install azure-ai-formrecognizer==3.3.0

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

using Azure;
using Azure.AI.FormRecognizer.DocumentAnalysis;

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

import com.azure.core.credential.AzureKeyCredential;

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

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

3.設定驗證

有兩種支援的驗證方法：

使用文件智慧 API 金鑰搭配 azure.core.credentials 中的 AzureKeyCredential。
使用來自 azure-identity 的權杖認證搭配 Microsoft Entra ID 進行驗證。

使用您的 API 金鑰

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

Azure 入口網站中金鑰和端點位置的螢幕擷取畫面。

重要

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

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

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


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


// create your `DocumentAnalysisClient` instance and `AzureKeyCredential` variable
DocumentAnalysisClient client = new DocumentAnalysisClientBuilder()
            .credential(new AzureKeyCredential("<your-key>"))
            .endpoint("<your-endpoint>")
            .buildClient();


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


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

使用 Microsoft Entra 權杖認證

注意

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

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

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

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

    dotnet add package Azure.Identity

    Install-Package Azure.Identity

註冊 Microsoft Entra 應用程式並建立新的服務主體。
將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。
將 Microsoft Entra 應用程式中用戶端識別碼、租用戶識別碼和用戶端密碼的值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

建立您的 DocumentAnalysisClient 執行個體，包括 DefaultAzureCredential：

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

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

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

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

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

註冊 Microsoft Entra 應用程式並建立新的服務主體。
將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。
將 Microsoft Entra 應用程式的用戶端識別碼、租用戶識別碼和用戶端密碼值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

建立您的 DocumentAnalysisClient 執行個體和 TokenCredential 變數：

TokenCredential credential = new DefaultAzureCredentialBuilder().build();
DocumentAnalysisClient documentAnalysisClient = new DocumentAnalysisClientBuilder()
    .endpoint("{your-endpoint}")
    .credential(credential)
    .buildClient();

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

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

安裝適用於 JavaScript 的 Azure 身分識別程式庫：
```
npm install @azure/identity
```
註冊 Microsoft Entra 應用程式並建立新的服務主體。
將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。
將 Microsoft Entra 應用程式的用戶端識別碼、租用戶識別碼和用戶端密碼值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

建立您的 DocumentAnalysisClient 執行個體，包括 DefaultAzureCredential：

const { DocumentAnalysisClient } = require("@azure/ai-form-recognizer");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new DocumentAnalysisClient("<your-endpoint>", new DefaultAzureCredential());

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

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

安裝適用於 Python 的 Azure 身分識別程式庫：
```
pip install azure-identity
```
註冊 Microsoft Entra 應用程式並建立新的服務主體。
將 Cognitive Services User 角色指派給服務主體，以授與對文件智慧的存取權。
將 Microsoft Entra 應用程式的用戶端識別碼、租用戶識別碼和用戶端密碼值分別設定為環境變數 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

建立您的 DocumentAnalysisClient 執行個體，包括 DefaultAzureCredential：

from azure.identity import DefaultAzureCredential
from azure.ai.formrecognizer import DocumentAnalysisClient

credential = DefaultAzureCredential()
document_analysis_client = DocumentAnalysisClient(
    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 2023-07-31 作業。

分享方式：

SDK 目標：REST API 2023-07-31 (GA)

支援的程式設計語言

支援的用戶端

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

1.安裝 SDK 用戶端程式庫

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

3.設定驗證

使用您的 API 金鑰

使用 Microsoft Entra 權杖認證

4.建置應用程式

說明選項

下一步

意見反映

更多資源