Azure AI Form Recognizer Client Library

Warnings

• breaking For API versions 2022-08-31 and later, you must use `DocumentAnalysisClient` and `DocumentModelAdministrationClient`. The older `FormRecognizerClient` is deprecated for these versions and only supports service API versions 2.1 and below.
  Fix: Migrate client instantiation from `FormRecognizerClient` to `DocumentAnalysisClient` or `DocumentModelAdministrationClient` as per service API version. Refer to migration guides for detailed changes.
• breaking As of SDK version 3.3.0 and service API version 2023-07-31 (now default), several properties and models were removed, including `query_fields` keyword argument, `DocumentPage.images`, `DocumentImage` model, `DocumentPage.annotations`, `DocumentAnnotation` model, and `DocumentKeyValuePair.common_name`. Some `AnalysisFeature` enum members were also renamed.
  Fix: Review the official changelog and migration guide for your specific version. Adapt code to use the new add-on capabilities (e.g., `features` parameter for barcodes, formulas, key-value pairs) instead of removed properties.
• deprecated The service name 'Azure Form Recognizer' was officially renamed to 'Azure AI Document Intelligence' in July 2023. While the Python package `azure-ai-formrecognizer` retains its name, documentation and service terminology refer to 'Document Intelligence'.
  Fix: Be aware of the name change when consulting documentation or troubleshooting. The underlying functionality remains the same.
• breaking As of `azure-ai-formrecognizer` version 3.3.3, Python 3.7 is no longer supported. The minimum required Python version is 3.8.
  Fix: Upgrade your Python environment to 3.8 or later.
• gotcha Common 'Unauthorized' errors (HTTP 401) often indicate an incorrect endpoint, an invalid or expired subscription key, or attempting Azure Active Directory (AAD) authentication on a regional endpoint (AAD requires a custom subdomain).
  Fix: Verify your `endpoint` and `key` against your Azure resource. Ensure the endpoint format is correct (e.g., `https://<your-resource-name>.cognitiveservices.azure.com/`). For AAD, confirm a custom subdomain is used and service principal has 'Cognitive Services User' role.
• gotcha Errors like 'InvalidContentSourceFormat', 'InvalidContent', or `DecodeError: JSON is invalid` for specific documents can stem from corrupted files, unsupported file types, incorrect SAS URLs, or issues with blob storage paths (e.g., an extra leading '/' in container paths can create a virtual directory that is not recognized).
  Fix: Validate document integrity and format. Check SAS token permissions and expiry. Ensure blob storage paths are correct without leading slashes if not intended. For `DecodeError` on long PDFs, try splitting documents or increasing service timeouts if available.

Install

• pip install azure-ai-formrecognizer Install stable version

Imports

• DocumentAnalysisClient

  from azure.ai.formrecognizer import DocumentAnalysisClient

  DocumentAnalysisClient is the primary client for API versions 2022-08-31 and higher (default for 3.x+ SDKs). FormRecognizerClient is for older API versions (v2.1 and below).
• DocumentModelAdministrationClient

  from azure.ai.formrecognizer import DocumentModelAdministrationClient

  Used for building, composing, and managing custom document models.
• AzureKeyCredential

  from azure.core.credentials import AzureKeyCredential

  Used for authenticating with an API key.

Quickstart

This quickstart demonstrates how to create a DocumentAnalysisClient, authenticate using an API key, and analyze a document from a URL using the 'prebuilt-document' model to extract general key-value pairs and other structural information. Remember to replace placeholder endpoint and key values with your actual Azure Form Recognizer resource credentials and provide a URL to your document.

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

# Set these environment variables for authentication
endpoint = os.environ.get('AZURE_FORM_RECOGNIZER_ENDPOINT', 'YOUR_FORM_RECOGNIZER_ENDPOINT')
key = os.environ.get('AZURE_FORM_RECOGNIZER_KEY', 'YOUR_FORM_RECOGNIZER_KEY')

if endpoint == 'YOUR_FORM_RECOGNIZER_ENDPOINT' or key == 'YOUR_FORM_RECOGNIZER_KEY':
    print("Please set the AZURE_FORM_RECOGNIZER_ENDPOINT and AZURE_FORM_RECOGNIZER_KEY environment variables.")
    exit()

# Example document URL (replace with your own)
document_url = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-quickstart-code/master/python/FormRecognizer/rest/sample_data/Form_1.jpg"

def analyze_general_document():
    document_analysis_client = DocumentAnalysisClient(
        endpoint=endpoint, credential=AzureKeyCredential(key)
    )

    print(f"Analyzing document from: {document_url}")
    # Use the prebuilt-document model for general document analysis
    poller = document_analysis_client.begin_analyze_document_from_url(
        "prebuilt-document", document_url
    )
    result = poller.result()

    if result.documents:
        for idx, doc in enumerate(result.documents):
            print(f"----Detected Document #{idx+1}-----")
            print(f"Document type: {doc.doc_type}")
            if doc.fields:
                print("Fields:")
                for name, field in doc.fields.items():
                    field_value = field.value if field.value else field.content
                    print(f"  {name}: {field_value} (Confidence: {field.confidence:.2f})")
    else:
        print("No documents detected.")

    print("---Analysis complete.---")

if __name__ == "__main__":
    analyze_general_document()