Azure Formularerkennung-Clientbibliothek für .NET – Version 4.1.0

Hinweis: Im Juli 2023 wurde der Azure Cognitive Services-Formularerkennung-Dienst in Azure AI Document Intelligence umbenannt. Alle Erwähnungen von Formularerkennung oder Document Intelligence in der Dokumentation beziehen sich auf denselben Azure-Dienst.

Azure AI Document Intelligence ist ein Clouddienst, der maschinelles Lernen verwendet, um Text und strukturierte Daten aus Ihren Dokumenten zu analysieren. Es enthält die folgenden Standard Features:

• Layout: Extrahieren Sie Text, Auswahlmarkierungen, Tabellenstrukturen, Formatvorlagen und Absätze sowie deren Begrenzungsbereichskoordinaten aus Dokumenten.
• Allgemeines Dokument: Analysieren Sie zusätzlich zum allgemeinen Layout von Dokumenten Schlüssel-Wert-Paare.
• Lesen: Lesen Sie zusätzlich zu Textsprachinformationen Informationen zu Textelementen, z. B. Seitenwörter und Zeilen.
• Vordefinierter Typ: Analysieren von Daten aus bestimmten Arten gängiger Dokumente mithilfe vordefinierter Modelle. Unterstützte Dokumente umfassen Belege, Rechnungen, Visitenkarten, Identitätsdokumente, US W2-Steuerformulare und vieles mehr.
• Benutzerdefinierte Analyse: Erstellen von benutzerdefinierten Dokumentmodellen zum Analysieren von Text, Feldwerten, Auswahlmarkierungen, Tabellenstrukturen, Formatvorlagen und Absätzen aus Dokumenten. Benutzerdefinierte Modelle werden mit Ihren eigenen Daten erstellt, sodass sie auf Ihre Dokumente zugeschnitten sind.
• Benutzerdefinierte Klassifizierung: Erstellen Sie benutzerdefinierte Klassifizierermodelle, die Layout- und Sprachfeatures kombinieren, um Dokumente, die Sie in Ihrer Anwendung verarbeiten, genau zu erkennen und zu identifizieren.

Quellcode | Paket (NuGet) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Formularerkennung-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.AI.FormRecognizer

Hinweis: Diese Version der Clientbibliothek verwendet standardmäßig die 2023-07-31 Version des Diensts.

Diese Tabelle gibt Aufschluss über die Beziehung zwischen SDK-Versionen und unterstützten API-Versionen des Diensts:

SDK-Version	Unterstützte API-Version des Diensts
4.1.0	2.0, 2.1, 2022-08-31, 2023-07-31
4.0.0	2.0, 2.1, 2022-08-31
3.1.X	2.0, 2.1
3.0.X	2.0

Hinweis: Ab version 4.0.0wurde eine neue Gruppe von Clients eingeführt, um die neuesten Features des Document Intelligence-Diensts zu nutzen. Ausführliche Anweisungen zum Aktualisieren von Anwendungscode von der Clientbibliotheksversion 3.1.X oder niedriger auf die neueste Version finden Sie im Migrationshandbuch. Ausführlichere Informationen finden Sie im Changelog . In der folgenden Tabelle wird die Beziehung zwischen den einzelnen Clients und den unterstützten API-Versionen beschrieben:

API-Version	Unterstützte Clients
2023-07-31	DocumentAnalysisClient und DocumentModelAdministrationClient
2022-08-31	DocumentAnalysisClient und DocumentModelAdministrationClient
2.1	FormRecognizerClient und FormTrainingClient
2.0	FormRecognizerClient und FormTrainingClient

Voraussetzungen

• Ein Azure-Abonnement.
• Eine Cognitive Services- oder Formularerkennung Ressource, um dieses Paket zu verwenden.

Erstellen einer Cognitive Services- oder Formularerkennung-Ressource

Document Intelligence unterstützt sowohl den Zugriff mit mehreren Diensten als auch den Einzeldienst. Erstellen Sie eine Cognitive Services-Ressource, wenn Sie planen, über einen einzelnen Endpunkt bzw. Schlüssel auf mehrere Cognitive Services-Instanzen zuzugreifen. Erstellen Sie nur für den Document Intelligence-Zugriff eine Formularerkennung-Ressource. Beachten Sie, dass Sie eine Einzeldienstressource benötigen, wenn Sie die Azure Active Directory-Authentifizierung verwenden möchten.

Sie können beide Ressourcen erstellen mit:

• Option 1: Azure-Portal.
• Option 2: Azure CLI.

Im Folgenden finden Sie ein Beispiel dafür, wie Sie eine Formularerkennung-Ressource mithilfe der CLI erstellen können:

# Create a new resource group to hold the Form Recognizer resource
# If using an existing resource group, skip this step
az group create --name <your-resource-name> --location <location>

# Create the Form Recognizer resource
az cognitiveservices account create \
    --name <resource-name> \
    --resource-group <resource-group-name> \
    --kind FormRecognizer \
    --sku <sku> \
    --location <location> \
    --yes

Weitere Informationen zum Erstellen der Ressource oder zum Abrufen des Speicherorts und der SKU-Informationen finden Sie hier.

Authentifizieren des Clients

Um mit dem Document Intelligence-Dienst zu interagieren, müssen Sie eine instance der DocumentAnalysisClient -Klasse erstellen. Ein Endpunkt und Anmeldeinformationen sind erforderlich, um das Clientobjekt zu instanziieren.

Abrufen des Endpunkts

Sie können den Endpunkt für Ihre Formularerkennung-Ressource über das Azure-Portal oder die Azure CLI finden:

# Get the endpoint for the Form Recognizer resource
az cognitiveservices account show --name "<resource-name>" --resource-group "<resource-group-name>" --query "properties.endpoint"

Für die Authentifizierung kann entweder ein regionaler Endpunkt oder eine benutzerdefinierte Unterdomäne verwendet werden. Sie sind wie folgt formatiert:

Regional endpoint: https://<region>.api.cognitive.microsoft.com/
Custom subdomain: https://<resource-name>.cognitiveservices.azure.com/

Ein regionaler Endpunkt ist für jede Ressource in einer Region identisch. Eine vollständige Liste der unterstützten regionalen Endpunkte finden Sie hier. Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen.

Eine benutzerdefinierte Unterdomäne hingegen ist ein Name, der für die Formularerkennung Ressource eindeutig ist. Sie können nur von Einzeldienstressourcen verwendet werden.

Abrufen des API-Schlüssels

Den API-Schlüssel finden Sie im Azure-Portal oder indem Sie den folgenden Azure CLI-Befehl ausführen:

az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"

Erstellen von DocumentAnalysisClient mit AzureKeyCredential

Wenn Sie über den Wert für den API-Schlüssel verfügen, erstellen Sie einen AzureKeyCredential. Mit dem Endpunkt und den Schlüsselanmeldeinformationen können Sie folgendes DocumentAnalysisClienterstellen:

string endpoint = "<endpoint>";
string apiKey = "<apiKey>";
var credential = new AzureKeyCredential(apiKey);
var client = new DocumentAnalysisClient(new Uri(endpoint), credential);

Erstellen von DocumentAnalysisClient mit Azure Active Directory-Anmeldeinformationen

AzureKeyCredential Die Authentifizierung wird in den Beispielen in diesem Leitfaden für die ersten Schritte verwendet. Sie können sich jedoch auch mithilfe der Azure Identity-Bibliothek bei Azure Active Directory authentifizieren. Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen. Erstellen Sie eine benutzerdefinierte Unterdomäne für Ihre Ressource, um diesen Authentifizierungstyp zu verwenden.

Um den unten gezeigten Anbieter DefaultAzureCredential oder andere Anbieter von Anmeldeinformationen zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie das Azure.Identity Paket:

dotnet add package Azure.Identity

Außerdem müssen Sie eine neue AAD-Anwendung registrieren und Zugriff auf Document Intelligence gewähren, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen.

Legen Sie die Werte der Client-ID, Mandanten-ID und geheimen Clientschlüssel der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

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

Wichtige Begriffe

DocumentAnalysisClient

DocumentAnalysisClient stellt Vorgänge für Folgendes bereit:

• Analysieren von Eingabedokumenten mithilfe vordefinierter und benutzerdefinierter Modelle über die AnalyzeDocument APIs und AnalyzeDocumentFromUri
• Erkennen und Identifizieren von benutzerdefinierten Eingabedokumenten mit den ClassifyDocument APIs und ClassifyDocumentFromUri

Beispielcodeausschnitte werden bereitgestellt, um die Verwendung eines DocumentAnalysisClients zu veranschaulichen. Weitere Informationen zur Analyse von Dokumenten, einschließlich unterstützter Features, Gebietsschemas und Dokumenttypen, finden Sie in der Dienstdokumentation.

DocumentModelAdministrationClient

DocumentModelAdministrationClient stellt Vorgänge für Folgendes bereit:

• Erstellen von benutzerdefinierten Modellen zum Analysieren bestimmter Felder, die Sie angeben, indem Sie Ihre benutzerdefinierten Dokumente beschriften. Ein DocumentModelDetails instance zurückgegeben wird, der die Dokumenttypen angibt, die das Modell analysieren kann, die Felder, die es für jeden Dokumenttyp analysieren kann, sowie die geschätzte Konfidenz für jedes Feld. Eine ausführlichere Erklärung finden Sie in der Dienstdokumentation .
• Erstellen Sie ein Modell aus einer Sammlung vorhandener Modelle.
• Verwalten der in Ihrem Konto erstellten Modelle
• Kopieren eines benutzerdefinierten Modells aus einer Formularerkennungsressource in eine andere
• Auflisten von Buildvorgängen oder Erstellen bestimmter Vorgänge innerhalb der letzten 24 Stunden
• Erstellen und Verwalten von Dokumentklassifizierungsmodellen, um Dokumente, die Sie in Ihrer Anwendung verarbeiten, genau zu erkennen und zu identifizieren.

Siehe Beispiele für Erstellen eines benutzerdefinierten Modells, Verwalten von Modellen und Erstellen eines Dokumentklassifizierungsbezeichners.

Beachten Sie, dass Modelle und Klassifizierer auch mithilfe einer grafischen Benutzeroberfläche wie Document Intelligence Studio erstellt werden können.

Long-Running Vorgänge

Da die Analyse von Dokumenten und Erstellungsmodellen Zeit in Anspruch nimmt, werden diese Vorgänge als langwierige Vorgänge implementiert. Vorgänge mit langer Ausführungsdauer bestehen aus einer anfänglichen Anforderung, die an den Dienst gesendet wird, um einen Vorgang zu starten, gefolgt von der Abfrage des Diensts in Intervallen, um festzustellen, ob der Vorgang abgeschlossen oder fehlgeschlagen ist, und wenn er erfolgreich war, um das Ergebnis zu erhalten.

Bei Vorgängen mit langer Ausführung im Azure SDK macht der Client eine Methode verfügbar, die ein Operation<T> Objekt zurückgibt. Sie können seinen Parameter waitUntil auf festlegen, um auf WaitUntil.Completed den Abschluss des Vorgangs zu warten und das Ergebnis abzurufen. Oder auf festlegen WaitUntil.Started , wenn Sie den Vorgang nur starten und das Ergebnis später nutzen möchten. Ein Beispielcodeausschnitt wird bereitgestellt, um die Verwendung von Vorgängen mit langer Ausführungsdauer unten zu veranschaulichen.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Behandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Der folgende Abschnitt enthält mehrere Codeausschnitte, die gängige Muster veranschaulichen, die in der Formularerkennung .NET-API verwendet werden. Die meisten der folgenden Codeausschnitte verwenden asynchrone Dienstaufrufe. Beachten Sie jedoch, dass das Azure.AI.FormRecognizer-Paket sowohl synchrone als auch asynchrone APIs unterstützt.

Asynchrone Beispiele

• Layout extrahieren
• Verwenden des vordefinierten allgemeinen Dokumentmodells
• Verwenden des vordefinierten Lesemodells
• Verwenden vordefinierter Modelle
• Erstellen eines benutzerdefinierten Modells
• Analysieren von benutzerdefinierten Dokumenten
• Modelle verwalten
• Erstellen einer Dokumentklassifizierung
• Klassifizieren eines Dokuments

Synchronisierungsbeispiele

• Synchrones Verwalten von Modellen

Beachten Sie, dass in diesen Beispielen die SDK-Version 4.1.0verwendet wird. Informationen zu Version 3.1.1 oder niedriger finden Sie unter Formularerkennung Beispiele für V3.1.X.

Layout extrahieren

Extrahieren Sie Text, Auswahlmarkierungen, Tabellenstrukturen, Formatvorlagen und Absätze sowie deren Begrenzungsbereichskoordinaten aus Dokumenten.

Uri fileUri = new Uri("<fileUri>");

AnalyzeDocumentOperation operation = await client.AnalyzeDocumentFromUriAsync(WaitUntil.Completed, "prebuilt-layout", fileUri);
AnalyzeResult result = operation.Value;

foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Document Page {page.PageNumber} has {page.Lines.Count} line(s), {page.Words.Count} word(s),");
    Console.WriteLine($"and {page.SelectionMarks.Count} selection mark(s).");

    for (int i = 0; i < page.Lines.Count; i++)
    {
        DocumentLine line = page.Lines[i];
        Console.WriteLine($"  Line {i} has content: '{line.Content}'.");

        Console.WriteLine($"    Its bounding polygon (points ordered clockwise):");

        for (int j = 0; j < line.BoundingPolygon.Count; j++)
        {
            Console.WriteLine($"      Point {j} => X: {line.BoundingPolygon[j].X}, Y: {line.BoundingPolygon[j].Y}");
        }
    }

    for (int i = 0; i < page.SelectionMarks.Count; i++)
    {
        DocumentSelectionMark selectionMark = page.SelectionMarks[i];

        Console.WriteLine($"  Selection Mark {i} is {selectionMark.State}.");
        Console.WriteLine($"    Its bounding polygon (points ordered clockwise):");

        for (int j = 0; j < selectionMark.BoundingPolygon.Count; j++)
        {
            Console.WriteLine($"      Point {j} => X: {selectionMark.BoundingPolygon[j].X}, Y: {selectionMark.BoundingPolygon[j].Y}");
        }
    }
}

Console.WriteLine("Paragraphs:");

foreach (DocumentParagraph paragraph in result.Paragraphs)
{
    Console.WriteLine($"  Paragraph content: {paragraph.Content}");

    if (paragraph.Role != null)
    {
        Console.WriteLine($"    Role: {paragraph.Role}");
    }
}

foreach (DocumentStyle style in result.Styles)
{
    // Check the style and style confidence to see if text is handwritten.
    // Note that value '0.8' is used as an example.

    bool isHandwritten = style.IsHandwritten.HasValue && style.IsHandwritten == true;

    if (isHandwritten && style.Confidence > 0.8)
    {
        Console.WriteLine($"Handwritten content found:");

        foreach (DocumentSpan span in style.Spans)
        {
            Console.WriteLine($"  Content: {result.Content.Substring(span.Index, span.Length)}");
        }
    }
}

Console.WriteLine("The following tables were extracted:");

for (int i = 0; i < result.Tables.Count; i++)
{
    DocumentTable table = result.Tables[i];
    Console.WriteLine($"  Table {i} has {table.RowCount} rows and {table.ColumnCount} columns.");

    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"    Cell ({cell.RowIndex}, {cell.ColumnIndex}) has kind '{cell.Kind}' and content: '{cell.Content}'.");
    }
}

Weitere Informationen und Beispiele finden Sie hier.

Verwenden des vordefinierten allgemeinen Dokumentmodells

Analysieren Von Text, Auswahlzeichen, Tabellenstrukturen, Formatvorlagen, Absätzen und Schlüssel-Wert-Paaren aus Dokumenten mithilfe des vordefinierten allgemeinen Dokumentmodells.

Uri fileUri = new Uri("<fileUri>");

AnalyzeDocumentOperation operation = await client.AnalyzeDocumentFromUriAsync(WaitUntil.Completed, "prebuilt-document", fileUri);
AnalyzeResult result = operation.Value;

Console.WriteLine("Detected key-value pairs:");

foreach (DocumentKeyValuePair kvp in result.KeyValuePairs)
{
    if (kvp.Value == null)
    {
        Console.WriteLine($"  Found key with no value: '{kvp.Key.Content}'");
    }
    else
    {
        Console.WriteLine($"  Found key-value pair: '{kvp.Key.Content}' and '{kvp.Value.Content}'");
    }
}

foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Document Page {page.PageNumber} has {page.Lines.Count} line(s), {page.Words.Count} word(s),");
    Console.WriteLine($"and {page.SelectionMarks.Count} selection mark(s).");

    for (int i = 0; i < page.Lines.Count; i++)
    {
        DocumentLine line = page.Lines[i];
        Console.WriteLine($"  Line {i} has content: '{line.Content}'.");

        Console.WriteLine($"    Its bounding polygon (points ordered clockwise):");

        for (int j = 0; j < line.BoundingPolygon.Count; j++)
        {
            Console.WriteLine($"      Point {j} => X: {line.BoundingPolygon[j].X}, Y: {line.BoundingPolygon[j].Y}");
        }
    }

    for (int i = 0; i < page.SelectionMarks.Count; i++)
    {
        DocumentSelectionMark selectionMark = page.SelectionMarks[i];

        Console.WriteLine($"  Selection Mark {i} is {selectionMark.State}.");
        Console.WriteLine($"    Its bounding polygon (points ordered clockwise):");

        for (int j = 0; j < selectionMark.BoundingPolygon.Count; j++)
        {
            Console.WriteLine($"      Point {j} => X: {selectionMark.BoundingPolygon[j].X}, Y: {selectionMark.BoundingPolygon[j].Y}");
        }
    }
}

foreach (DocumentStyle style in result.Styles)
{
    // Check the style and style confidence to see if text is handwritten.
    // Note that value '0.8' is used as an example.

    bool isHandwritten = style.IsHandwritten.HasValue && style.IsHandwritten == true;

    if (isHandwritten && style.Confidence > 0.8)
    {
        Console.WriteLine($"Handwritten content found:");

        foreach (DocumentSpan span in style.Spans)
        {
            Console.WriteLine($"  Content: {result.Content.Substring(span.Index, span.Length)}");
        }
    }
}

Console.WriteLine("The following tables were extracted:");

for (int i = 0; i < result.Tables.Count; i++)
{
    DocumentTable table = result.Tables[i];
    Console.WriteLine($"  Table {i} has {table.RowCount} rows and {table.ColumnCount} columns.");

    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"    Cell ({cell.RowIndex}, {cell.ColumnIndex}) has kind '{cell.Kind}' and content: '{cell.Content}'.");
    }
}

Weitere Informationen und Beispiele finden Sie hier.

Verwenden des vordefinierten Lesemodells

Analysieren Sie Textelemente wie Seitenwörter und Zeilen, Formatvorlagen, Absätze und Textsprachinformationen aus Dokumenten mithilfe des vordefinierten Lesemodells.

Uri fileUri = new Uri("<fileUri>");

AnalyzeDocumentOperation operation = await client.AnalyzeDocumentFromUriAsync(WaitUntil.Completed, "prebuilt-read", fileUri);
AnalyzeResult result = operation.Value;

Console.WriteLine("Detected languages:");

foreach (DocumentLanguage language in result.Languages)
{
    Console.WriteLine($"  Found language with locale '{language.Locale}' and confidence {language.Confidence}.");
}

foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Document Page {page.PageNumber} has {page.Lines.Count} line(s), {page.Words.Count} word(s),");
    Console.WriteLine($"and {page.SelectionMarks.Count} selection mark(s).");

    for (int i = 0; i < page.Lines.Count; i++)
    {
        DocumentLine line = page.Lines[i];
        Console.WriteLine($"  Line {i} has content: '{line.Content}'.");

        Console.WriteLine($"    Its bounding polygon (points ordered clockwise):");

        for (int j = 0; j < line.BoundingPolygon.Count; j++)
        {
            Console.WriteLine($"      Point {j} => X: {line.BoundingPolygon[j].X}, Y: {line.BoundingPolygon[j].Y}");
        }
    }
}

foreach (DocumentStyle style in result.Styles)
{
    // Check the style and style confidence to see if text is handwritten.
    // Note that value '0.8' is used as an example.

    bool isHandwritten = style.IsHandwritten.HasValue && style.IsHandwritten == true;

    if (isHandwritten && style.Confidence > 0.8)
    {
        Console.WriteLine($"Handwritten content found:");

        foreach (DocumentSpan span in style.Spans)
        {
            Console.WriteLine($"  Content: {result.Content.Substring(span.Index, span.Length)}");
        }
    }
}

Weitere Informationen und Beispiele finden Sie hier.

Verwenden vordefinierter Modelle

Analysieren Sie Daten aus bestimmten Arten allgemeiner Dokumente mithilfe vordefinierter Modelle, die vom Document Intelligence-Dienst bereitgestellt werden.

Um beispielsweise Felder aus einer Rechnung zu analysieren, verwenden Sie das vordefinierte Rechnungsmodell, das durch Übergeben der prebuilt-invoice Modell-ID an die AnalyzeDocumentAsync -Methode bereitgestellt wird:

string filePath = "<filePath>";

using var stream = new FileStream(filePath, FileMode.Open);

AnalyzeDocumentOperation operation = await client.AnalyzeDocumentAsync(WaitUntil.Completed, "prebuilt-invoice", stream);
AnalyzeResult result = operation.Value;

// To see the list of all the supported fields returned by service and its corresponding types for the
// prebuilt-invoice model, consult:
// https://aka.ms/azsdk/formrecognizer/invoicefieldschema

for (int i = 0; i < result.Documents.Count; i++)
{
    Console.WriteLine($"Document {i}:");

    AnalyzedDocument document = result.Documents[i];

    if (document.Fields.TryGetValue("VendorName", out DocumentField vendorNameField))
    {
        if (vendorNameField.FieldType == DocumentFieldType.String)
        {
            string vendorName = vendorNameField.Value.AsString();
            Console.WriteLine($"Vendor Name: '{vendorName}', with confidence {vendorNameField.Confidence}");
        }
    }

    if (document.Fields.TryGetValue("CustomerName", out DocumentField customerNameField))
    {
        if (customerNameField.FieldType == DocumentFieldType.String)
        {
            string customerName = customerNameField.Value.AsString();
            Console.WriteLine($"Customer Name: '{customerName}', with confidence {customerNameField.Confidence}");
        }
    }

    if (document.Fields.TryGetValue("Items", out DocumentField itemsField))
    {
        if (itemsField.FieldType == DocumentFieldType.List)
        {
            foreach (DocumentField itemField in itemsField.Value.AsList())
            {
                Console.WriteLine("Item:");

                if (itemField.FieldType == DocumentFieldType.Dictionary)
                {
                    IReadOnlyDictionary<string, DocumentField> itemFields = itemField.Value.AsDictionary();

                    if (itemFields.TryGetValue("Description", out DocumentField itemDescriptionField))
                    {
                        if (itemDescriptionField.FieldType == DocumentFieldType.String)
                        {
                            string itemDescription = itemDescriptionField.Value.AsString();

                            Console.WriteLine($"  Description: '{itemDescription}', with confidence {itemDescriptionField.Confidence}");
                        }
                    }

                    if (itemFields.TryGetValue("Amount", out DocumentField itemAmountField))
                    {
                        if (itemAmountField.FieldType == DocumentFieldType.Currency)
                        {
                            CurrencyValue itemAmount = itemAmountField.Value.AsCurrency();

                            Console.WriteLine($"  Amount: '{itemAmount.Symbol}{itemAmount.Amount}', with confidence {itemAmountField.Confidence}");
                        }
                    }
                }
            }
        }
    }

    if (document.Fields.TryGetValue("SubTotal", out DocumentField subTotalField))
    {
        if (subTotalField.FieldType == DocumentFieldType.Currency)
        {
            CurrencyValue subTotal = subTotalField.Value.AsCurrency();
            Console.WriteLine($"Sub Total: '{subTotal.Symbol}{subTotal.Amount}', with confidence {subTotalField.Confidence}");
        }
    }

    if (document.Fields.TryGetValue("TotalTax", out DocumentField totalTaxField))
    {
        if (totalTaxField.FieldType == DocumentFieldType.Currency)
        {
            CurrencyValue totalTax = totalTaxField.Value.AsCurrency();
            Console.WriteLine($"Total Tax: '{totalTax.Symbol}{totalTax.Amount}', with confidence {totalTaxField.Confidence}");
        }
    }

    if (document.Fields.TryGetValue("InvoiceTotal", out DocumentField invoiceTotalField))
    {
        if (invoiceTotalField.FieldType == DocumentFieldType.Currency)
        {
            CurrencyValue invoiceTotal = invoiceTotalField.Value.AsCurrency();
            Console.WriteLine($"Invoice Total: '{invoiceTotal.Symbol}{invoiceTotal.Amount}', with confidence {invoiceTotalField.Confidence}");
        }
    }
}

Sie sind nicht auf Rechnungen beschränkt! Es stehen einige vordefinierte Modelle zur Auswahl, von denen jedes über einen eigenen Satz unterstützter Felder verfügt. Weitere Informationen zu den unterstützten Dokumenttypen finden Sie in der Dienstdokumentation.

Weitere Informationen und Beispiele finden Sie hier.

Erstellen eines benutzerdefinierten Modells

Erstellen Sie ein benutzerdefiniertes Modell für Ihren eigenen Dokumenttyp. Das resultierende Modell kann verwendet werden, um Werte aus den Dokumententypen zu analysieren, auf der es erstellt wurde.

// For this sample, you can use the training documents found in the `trainingFiles` folder.
// Upload the documents to your storage container and then generate a container SAS URL. Note
// that a container URI without SAS is accepted only when the container is public or has a
// managed identity configured.
//
// For instructions to set up documents for training in an Azure Blob Storage Container, please see:
// https://aka.ms/azsdk/formrecognizer/buildcustommodel

Uri blobContainerUri = new Uri("<blobContainerUri>");
var client = new DocumentModelAdministrationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

// We are selecting the Template build mode in this sample. For more information about the available
// build modes and their differences, please see:
// https://aka.ms/azsdk/formrecognizer/buildmode

BuildDocumentModelOperation operation = await client.BuildDocumentModelAsync(WaitUntil.Completed, blobContainerUri, DocumentBuildMode.Template);
DocumentModelDetails model = operation.Value;

Console.WriteLine($"  Model Id: {model.ModelId}");
Console.WriteLine($"  Created on: {model.CreatedOn}");

Console.WriteLine("  Document types the model can recognize:");
foreach (KeyValuePair<string, DocumentTypeDetails> documentType in model.DocumentTypes)
{
    Console.WriteLine($"    Document type: {documentType.Key} which has the following fields:");
    foreach (KeyValuePair<string, DocumentFieldSchema> schema in documentType.Value.FieldSchema)
    {
        Console.WriteLine($"    Field: {schema.Key} with confidence {documentType.Value.FieldConfidence[schema.Key]}");
    }
}

Weitere Informationen und Beispiele finden Sie hier.

Analysieren von benutzerdefinierten Dokumenten

Analysieren Sie Text, Feldwerte, Auswahlmarkierungen und Tabellenstrukturen, Formatvorlagen und Absätze aus benutzerdefinierten Dokumenten mithilfe von Modellen, die Sie mit Ihren eigenen Dokumenttypen erstellt haben.

string modelId = "<modelId>";
Uri fileUri = new Uri("<fileUri>");

AnalyzeDocumentOperation operation = await client.AnalyzeDocumentFromUriAsync(WaitUntil.Completed, modelId, fileUri);
AnalyzeResult result = operation.Value;

Console.WriteLine($"Document was analyzed with model with ID: {result.ModelId}");

foreach (AnalyzedDocument document in result.Documents)
{
    Console.WriteLine($"Document of type: {document.DocumentType}");

    foreach (KeyValuePair<string, DocumentField> fieldKvp in document.Fields)
    {
        string fieldName = fieldKvp.Key;
        DocumentField field = fieldKvp.Value;

        Console.WriteLine($"Field '{fieldName}': ");

        Console.WriteLine($"  Content: '{field.Content}'");
        Console.WriteLine($"  Confidence: '{field.Confidence}'");
    }
}

Weitere Informationen und Beispiele finden Sie hier.

Verwalten von Modellen

Verwalten Sie die in Ihrem Konto gespeicherten Modelle.

var client = new DocumentModelAdministrationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

// Check number of custom models in the Form Recognizer resource, and the maximum number of custom models that can be stored.
ResourceDetails resourceDetails = await client.GetResourceDetailsAsync();
Console.WriteLine($"Resource has {resourceDetails.CustomDocumentModelCount} custom models.");
Console.WriteLine($"It can have at most {resourceDetails.CustomDocumentModelLimit} custom models.");

// List the first ten or fewer models currently stored in the resource.
AsyncPageable<DocumentModelSummary> models = client.GetDocumentModelsAsync();

int count = 0;
await foreach (DocumentModelSummary modelSummary in models)
{
    Console.WriteLine($"Custom Model Summary:");
    Console.WriteLine($"  Model Id: {modelSummary.ModelId}");
    if (string.IsNullOrEmpty(modelSummary.Description))
        Console.WriteLine($"  Model description: {modelSummary.Description}");
    Console.WriteLine($"  Created on: {modelSummary.CreatedOn}");
    if (++count == 10)
        break;
}

// Create a new model to store in the resource.
Uri blobContainerUri = new Uri("<blobContainerUri>");
BuildDocumentModelOperation operation = await client.BuildDocumentModelAsync(WaitUntil.Completed, blobContainerUri, DocumentBuildMode.Template);
DocumentModelDetails model = operation.Value;

// Get the model that was just created.
DocumentModelDetails newCreatedModel = await client.GetDocumentModelAsync(model.ModelId);

Console.WriteLine($"Custom Model with Id {newCreatedModel.ModelId} has the following information:");

Console.WriteLine($"  Model Id: {newCreatedModel.ModelId}");
if (string.IsNullOrEmpty(newCreatedModel.Description))
    Console.WriteLine($"  Model description: {newCreatedModel.Description}");
Console.WriteLine($"  Created on: {newCreatedModel.CreatedOn}");

// Delete the model from the resource.
await client.DeleteDocumentModelAsync(newCreatedModel.ModelId);

Weitere Informationen und Beispiele finden Sie hier.

Synchrones Verwalten von Modellen

Verwalten Sie die in Ihrem Konto gespeicherten Modelle mit einer synchronen API.

var client = new DocumentModelAdministrationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

// Check number of custom models in the Form Recognizer resource, and the maximum number of custom models that can be stored.
ResourceDetails resourceDetails = client.GetResourceDetails();
Console.WriteLine($"Resource has {resourceDetails.CustomDocumentModelCount} custom models.");
Console.WriteLine($"It can have at most {resourceDetails.CustomDocumentModelLimit} custom models.");

// List the first ten or fewer models currently stored in the resource.
Pageable<DocumentModelSummary> models = client.GetDocumentModels();

foreach (DocumentModelSummary modelSummary in models.Take(10))
{
    Console.WriteLine($"Custom Model Summary:");
    Console.WriteLine($"  Model Id: {modelSummary.ModelId}");
    if (string.IsNullOrEmpty(modelSummary.Description))
        Console.WriteLine($"  Model description: {modelSummary.Description}");
    Console.WriteLine($"  Created on: {modelSummary.CreatedOn}");
}

// Create a new model to store in the resource.

Uri blobContainerUri = new Uri("<blobContainerUri>");
BuildDocumentModelOperation operation = client.BuildDocumentModel(WaitUntil.Completed, blobContainerUri, DocumentBuildMode.Template);
DocumentModelDetails model = operation.Value;

// Get the model that was just created.
DocumentModelDetails newCreatedModel = client.GetDocumentModel(model.ModelId);

Console.WriteLine($"Custom Model with Id {newCreatedModel.ModelId} has the following information:");

Console.WriteLine($"  Model Id: {newCreatedModel.ModelId}");
if (string.IsNullOrEmpty(newCreatedModel.Description))
    Console.WriteLine($"  Model description: {newCreatedModel.Description}");
Console.WriteLine($"  Created on: {newCreatedModel.CreatedOn}");

// Delete the created model from the resource.
client.DeleteDocumentModel(newCreatedModel.ModelId);

Erstellen einer Dokumentklassifizierung

Erstellen Sie einen Dokumentklassifizierungsbezeichner, indem Sie benutzerdefinierte Trainingsdokumente hochladen.

// For this sample, you can use the training documents found in the `classifierTrainingFiles` folder.
// Upload the documents to your storage container and then generate a container SAS URL. Note
// that a container URI without SAS is accepted only when the container is public or has a
// managed identity configured.
//
// For instructions to set up documents for training in an Azure Blob Storage Container, please see:
// https://aka.ms/azsdk/formrecognizer/buildclassifiermodel

Uri trainingFilesUri = new Uri("<trainingFilesUri>");
var client = new DocumentModelAdministrationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

var sourceA = new BlobContentSource(trainingFilesUri) { Prefix = "IRS-1040-A/train" };
var sourceB = new BlobContentSource(trainingFilesUri) { Prefix = "IRS-1040-B/train" };

var documentTypes = new Dictionary<string, ClassifierDocumentTypeDetails>()
{
    { "IRS-1040-A", new ClassifierDocumentTypeDetails(sourceA) },
    { "IRS-1040-B", new ClassifierDocumentTypeDetails(sourceB) }
};

BuildDocumentClassifierOperation operation = await client.BuildDocumentClassifierAsync(WaitUntil.Completed, documentTypes);
DocumentClassifierDetails classifier = operation.Value;

Console.WriteLine($"  Classifier Id: {classifier.ClassifierId}");
Console.WriteLine($"  Created on: {classifier.CreatedOn}");

Console.WriteLine("  Document types the classifier can recognize:");
foreach (KeyValuePair<string, ClassifierDocumentTypeDetails> documentType in classifier.DocumentTypes)
{
    Console.WriteLine($"    {documentType.Key}");
}

Weitere Informationen und Beispiele finden Sie hier.

Klassifizieren eines Dokuments

Verwenden Sie Dokumentklassifizierer, um Dokumente, die Sie in Ihrer Anwendung verarbeiten, genau zu erkennen und zu identifizieren.

string classifierId = "<classifierId>";
Uri fileUri = new Uri("<fileUri>");

ClassifyDocumentOperation operation = await client.ClassifyDocumentFromUriAsync(WaitUntil.Completed, classifierId, fileUri);
AnalyzeResult result = operation.Value;

Console.WriteLine($"Document was classified by classifier with ID: {result.ModelId}");

foreach (AnalyzedDocument document in result.Documents)
{
    Console.WriteLine($"Document of type: {document.DocumentType}");
}

Weitere Informationen und Beispiele finden Sie hier.

Problembehandlung

Allgemein

Wenn Sie mit der Formularerkennung Clientbibliothek mithilfe des .NET SDK interagieren, führen vom Dienst zurückgegebene Fehler zu einem RequestFailedException mit demselben HTTP-status Code, der von der REST-API-Anforderung zurückgegeben wird.

Wenn Sie beispielsweise ein Belegbild mit einem ungültigen Urisenden, wird ein 400 Fehler zurückgegeben, der "Ungültige Anforderung" angibt.

try
{
    AnalyzeDocumentOperation operation = await client.AnalyzeDocumentFromUriAsync(WaitUntil.Completed, "prebuilt-receipt", new Uri("http://invalid.uri"));
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Sie werden feststellen, dass zusätzliche Informationen protokolliert werden, z. B. die Clientanforderungs-ID des Vorgangs.

Message:
    Azure.RequestFailedException: Service request failed.
    Status: 400 (Bad Request)
    ErrorCode: InvalidRequest

Content:
    {"error":{"code":"InvalidRequest","message":"Invalid request.","innererror":{"code":"InvalidContent","message":"The file is corrupted or format is unsupported. Refer to documentation for the list of supported formats."}}}

Headers:
    Transfer-Encoding: chunked
    x-envoy-upstream-service-time: REDACTED
    apim-request-id: REDACTED
    Strict-Transport-Security: REDACTED
    X-Content-Type-Options: REDACTED
    Date: Fri, 01 Oct 2021 02:55:44 GMT
    Content-Type: application/json; charset=utf-8

Fehlercodes und Meldungen, die vom Document Intelligence-Dienst ausgelöst werden, finden Sie in der Dienstdokumentation.

Weitere Informationen zu häufigen Problemen finden Sie in unserem Leitfaden zur Problembehandlung.

Einrichten der Konsolenprotokollierung

Die einfachste Möglichkeit, die Protokolle anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren. Verwenden Sie die AzureEventSourceListener.CreateConsoleLogger-Methode, um einen Azure SDK-Protokolllistener zu erstellen, der Nachrichten an die Konsole ausgibt.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Weitere Informationen zu anderen Protokollierungsmechanismen finden Sie unter Diagnosebeispiele.

Nächste Schritte

Beispiele zur Verwendung der Formularerkennung-Bibliothek sind in diesem GitHub-Repository verfügbar. Beispiele werden für jeden Standard Funktionsbereich bereitgestellt:

• Extrahieren des Layouts eines Dokuments
• Analysieren mit dem vordefinierten allgemeinen Dokumentmodell
• Analysieren mit dem vordefinierten Lesemodell
• Analysieren eines Dokuments mit einem benutzerdefinierten Modell
• Analysieren eines Dokuments mit einem vordefinierten Modell
• Erstellen eines benutzerdefinierten Modells
• Verwalten von Modellen
• [Klassifizieren eines Dokuments] [classify_a_document]
• Erstellen einer Dokumentklassifizierung
• Abrufen und Auflisten von Dokumentmodellvorgängen
• Erstellen eines Modells
• Kopieren eines benutzerdefinierten Modells zwischen Formularerkennungsressourcen
• Simulieren eines Clients zum Testen mithilfe der Moq-Bibliothek

Beachten Sie, dass in diesen Beispielen die SDK-Version 4.1.0verwendet wird. Informationen zu Version 3.1.1 oder niedriger finden Sie unter Formularerkennung Beispiele für V3.1.X.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.