SDK target: REST API 2024-07-31-preview
Important
- Document Intelligence public preview releases provide early access to features that are in active development. Features, approaches, and processes may change, prior to General Availability (GA), based on user feedback.
- The public preview version of Document Intelligence client libraries default to REST API version 2024-07-31-preview.
- Public preview version 2024-07-31-preview is currently only available in the following Azure regions. Note that the custom generative (document field extraction) model in AI Foundry portal is only available in North Central US region:
- East US
- West US2
- West Europe
- North Central US
REST API version 2024-07-31-preview
Azure AI Document Intelligence is a cloud service that uses machine learning to analyze text and structured data from documents. The Document Intelligence software development kit (SDK) is a set of libraries and tools that enable you to easily integrate Document Intelligence models and capabilities into your applications. Document Intelligence SDK is available across platforms in C#/.NET, Java, JavaScript, and Python programming languages.
Supported programming languages
Document Intelligence SDK supports the following languages and platforms:
Language → Document Intelligence SDK version | Package | Supported API version | Platform support |
---|---|---|---|
.NET/C# → 1.0.0-beta.3 (preview) | NuGet | 2024-07-31 (preview) | Windows, macOS, Linux, Docker |
Java → 1.0.0-beta.4 (preview) | Maven repository | 2024-07-31 (preview) | Windows, macOS, Linux |
JavaScript → 1.0.0-beta.3 (preview) | npm | 2024-07-31 (preview) | Browser, Windows, macOS, Linux |
Python → 1.0.0b4 (preview) | PyPI | 2024-07-31 (preview) | Windows, macOS, Linux |
For more information on other SDK versions, see:
Supported Clients
The following tables present the correlation between each SDK version the supported API versions of the Document Intelligence service.
Language | SDK alias | API version (default) | Supported clients |
---|---|---|---|
.NET/C# 1.0.0-beta.2 (preview) | v4.0 (preview) | 2024-07-31-preview | DocumentIntelligenceClient DocumentIntelligenceAdministrationClient |
.NET/C# 4.1.0 | v3.1 latest (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 |
Use Document Intelligence SDK in your applications
The Document Intelligence SDK enables the use and management of the Document Intelligence service in your application. The SDK builds on the underlying Document Intelligence REST API allowing you to easily use those APIs within your programming language paradigm. Here's how you use the Document Intelligence SDK for your preferred language:
1. Install the SDK client library
dotnet add package Azure.AI.DocumentIntelligence --prerelease
Install-Package Azure.AI.FormRecognizer -Version 1.0.0-beta.3
2. Import the SDK client library into your application
using Azure;
using Azure.AI.DocumentIntelligence;
3. Set up authentication
There are two supported methods for authentication:
Use a Document Intelligence API key with AzureKeyCredential from azure.core.credentials.
Use a token credential from azure-identity to authenticate with Microsoft Entra ID.
Use your API key
Here's where to find your Document Intelligence API key in the Azure portal:
Important
We recommend Microsoft Entra ID authentication with managed identities for Azure resources to avoid storing credentials with your applications that run in the cloud.
If you use an API key, store it securely somewhere else, such as in Azure Key Vault. Don't include the API key directly in your code, and never post it publicly.
For more information about AI services security, see Authenticate requests to Azure AI services.
//set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal to create your `AzureKeyCredential` and `DocumentIntelligenceClient` instance
string key = "<your-key>";
string endpoint = "<your-endpoint>";
AzureKeyCredential credential = new AzureKeyCredential(key);
DocumentIntelligenceClient client = new DocumentIntelligenceClient(new Uri(endpoint), new AzureKeyCredential(key));
Use a Microsoft Entra token credential
Note
Regional endpoints do not support Microsoft Entra authentication. Create a custom subdomain for your resource in order to use this type of authentication.
Authorization is easiest using the DefaultAzureCredential
. It provides a default token credential, based upon the running environment, capable of handling most Azure authentication scenarios.
Here's how to acquire and use the DefaultAzureCredential for .NET applications:
Install the Azure Identity library for .NET:
dotnet add package Azure.Identity
Install-Package Azure.Identity
Register a Microsoft Entra application and create a new service principal.
Grant access to Document Intelligence by assigning the
Cognitive Services User
role to your service principal.Set the values of the client ID, tenant ID, and client secret in the Microsoft Entra application as environment variables:
AZURE_CLIENT_ID
,AZURE_TENANT_ID
, andAZURE_CLIENT_SECRET
, respectively.Create your
DocumentIntelligenceClient
instance including theDefaultAzureCredential
:string endpoint = "<your-endpoint>"; var client = new DocumentIntelligenceClient(new Uri(endpoint), new DefaultAzureCredential());
For more information, see Authenticate the client.
4. Build your application
Create a client object to interact with the Document Intelligence SDK, and then call methods on that client object to interact with the service. The SDKs provide both synchronous and asynchronous methods. For more insight, try a quickstart in a language of your choice.
Help options
The Microsoft Q&A
and Stack Overflow forums are available for the developer community to ask and answer questions about Azure AI Document Intelligence and other services. Microsoft monitors the forums and replies to questions that the community has yet to answer. To make sure, use the following tags so that we see your question.
Microsoft Q&A
:Azure AI Document Intelligence
.Stack Overflow:
azure-ai-document-intelligence
.
Next steps
Explore Document Intelligence REST API 2023-10-31-rest operations.