Migration der Formularerkennung v3.0

Wichtig

Die Formularerkennungs-REST-API v3.0 führt Breaking Changes in der REST-API-Anforderung ein und analysiert den JSON-Code der Antwort.

Migrieren von einer Vorschau-API der Version 3.0

Vorschau-APIs werden regelmäßig ausgemustert. Wenn Sie eine Version einer Vorschau-API verwenden, planen Sie die Aktualisierung Ihrer Anwendung, um die allgemein verfügbare API-Version zu verwenden, sobald diese verfügbar ist. Wenn Sie mithilfe des SDK von der API-Version 2021-09-30-preview oder 2022-01-30-preview zur (allgemein verfügbaren) API-Version 2022-08-31 migrieren möchten, aktualisieren Sie die aktuelle Version des sprachspezifischen SDK.

Die API 2022-08-31 enthält einige Updates aus den API-Vorschauversionen:

  • Das Feld „boundingBox“ wurde in „polygon“ umbenannt, um nicht vierseitige Polygonbereiche zu unterstützen.
  • Feld gelöscht: Entitäten wurden aus dem Ergebnis des allgemeinen Dokumentmodells entfernt.
  • Das Feld „documentLanguage.languageCode“ wurde in „locale“umbenannt.
  • Unterstützung für HEIF-Format hinzugefügt
  • Absatzerkennung hinzugefügt, mit Rollenklassifizierung für Layout und allgemeine Dokumentmodelle
  • Unterstützung für analysierte Adressfelder hinzugefügt

Migrieren von v2.1

Formularerkennung v3.0 bietet eine Reihe neuer Features und Möglichkeiten:

In diesem Artikel erfahren Sie mehr über die Unterschiede zwischen Formularerkennung v2.1 und v3.0 und wie Sie zur neueren Version der API wechseln.

Achtung

  • Das REST-API-Release 2022-08-31 enthält einen Breaking Change in der REST-API zum Analysieren von JSON-Antwortcode.
  • Die Eigenschaft boundingBox wird in jeder Instanz in polygon umbenannt.

Änderungen an den REST-API-Endpunkten

Die REST-API v3.0 kombiniert die Analysevorgänge für die Layoutanalyse, vordefinierte Modelle und benutzerdefinierte Modelle zu einem einzelnen Paar von Vorgängen, indem documentModels und modelId der Layoutanalyse (vordefiniertes Layout) und vordefinierten Modellen zugewiesen werden.

POST-Anforderung

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

GET-Anforderung

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2022-08-31

Analysevorgang

  • Die Anforderungsnutzdaten und das Aufrufmuster bleiben unverändert.
  • Der Analysevorgang gibt das Eingabedokument und inhaltsspezifische Konfigurationen an. Er gibt die Analyseergebnis-URL über den Operation-Location-Header in der Antwort zurück.
  • Fordern Sie diese Analyseergebnis-URL über eine GET-Anforderung an, um den Status des Analysevorgangs zu überprüfen (das empfohlene Mindestintervall zwischen Anforderungen beträgt 1 Sekunde).
  • Bei Erfolg wird der Status auf „Erfolgreich“ festgelegt und analyzeResult im Antworttext zurückgegeben. Treten Fehler auf, wird der Status auf failed festgelegt und ein Fehler zurückgegeben.
Modell v2.1 v3.0
Anforderungs-URL-Präfix https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
/documentModels/prebuilt-document:analyze
Layout /layout/analyze /documentModels/prebuilt-layout:analyze
Benutzerdefiniert /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Rechnung /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Rechnung /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
ID-Dokument /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Visitenkarte /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 /prebuilt/w-2/analyze /documentModels/prebuilt-w-2:analyze

Analysieren des Anforderungstexts

Der zu analysierende Inhalt wird über den Anforderungstext bereitgestellt. Entweder die URL- oder Base64-codierten Daten können Benutzer sein, um die Anforderung zu erstellen.

Um eine öffentlich zugängliche Web-URL anzugeben, setzen Sie Content-Type auf application/json und senden Sie den folgenden JSON-Text:

{
  "urlSource": "{urlPath}"
}

Die Base64-Codierung wird auch in der Formularerkennung v3.0 unterstützt:

{
  "base64Source": "{base64EncodedContent}"
}

Zusätzlich unterstützte Parameter

Parameter, die weiterhin unterstützt werden:

  • pages: Analysiert nur eine bestimmte Teilmenge von Seiten im Dokument. Liste der indizierten Seitenzahlen für die Analyse (beginnend ab der Zahl 1). Ex. 1-3,5,7-9
  • locale: Gebietsschemahinweis für die Texterkennung und Dokumentanalyse. Der Wert darf nur den Sprachcode (z. B. „en“, „fr“) oder das BCP-47-Sprachtag (z. B. „en-US“) enthalten.

Parameter, die nicht mehr unterstützt werden:

  • includeTextDetails

Das neue Antwortformat ist kompakter, und die vollständige Ausgabe wird immer zurückgegeben.

Änderungen zum Analysieren des Ergebnisses

Die Analyseantwort wurde auf die folgenden Ergebnisse der obersten Ebene umgestaltet, um mehrseitige Elemente zu unterstützen.

  • pages
  • tables
  • keyValuePairs
  • entities
  • styles
  • documents

Hinweis

Die analyzeResult-Antwortänderungen umfassen eine Reihe von Änderungen, z. B. der Wechsel von einer Eigenschaft von Seiten zu einer Eigenschaft auf oberster Ebene in analyzeResult.


{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
], // List of extracted entities
"entities": [
{
"category": "DateTime", // Primary entity category
"subCategory": "Date", // Secondary entity category
"content": "11/15/2019", // Entity content
"boundingRegions": [ ... ], // Entity bounding regions
"spans": [ ... ], // Entity spans
"confidence": 0.99 // Extraction confidence
}, ...
], // List of extracted styles
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

Erstellen oder Trainieren eines Modells

Das Modellobjekt verfügt in der neuen API über drei Updates.

  • modelId ist jetzt eine Eigenschaft, die für ein Modell für einen lesbaren Namen festgelegt werden kann.
  • modelName wurde in description umbenannt.
  • buildMode ist eine neue Eigenschaft mit dem Wert template für benutzerdefinierte Formularmodelle oder neural für benutzerdefinierte neuronale Modelle.

Der build-Vorgang wird aufgerufen, um ein Modell zu trainieren. Die Anforderungsnutzdaten und das Aufrufmuster bleiben unverändert. Der Erstellungsvorgang gibt das Modell und das Trainingsdataset an und gibt das Ergebnis über den Operation-Location-Header in der Antwort zurück. Fordern Sie diese Modellvorgangs-URL über eine GET-Anforderung an, um den Status des Erstellungsvorgangs zu überprüfen (das empfohlene Mindestintervall zwischen Anforderungen beträgt 1 Sekunde). Im Gegensatz zu v2.1 ist diese URL nicht der Ressourcenspeicherort des Modells. Stattdessen kann die Modell-URL aus der angegebenen Modell-ID konstruiert werden, die auch aus der resourceLocation-Eigenschaft in der Antwort abgerufen wird. Bei Erfolg wird der Status auf succeeded festgelegt, und das Ergebnis enthält die benutzerdefinierten Modellinformationen. Wenn Fehler auftreten, wird der Status auf failed festgelegt und der Fehler zurückgegeben.

Der folgende Code ist eine Beispielbuildanforderung mit einem SAS-Token. Beachten Sie beim Festlegen des Präfix- oder Ordnerpfads den nachgestellten Schrägstrich.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

Änderungen beim Zusammenstellen des Modells

Das Zusammensetzen von Modellen ist jetzt auf eine einzelne Schachtelungsebene beschränkt. Zusammengestellte Modelle sind jetzt mit benutzerdefinierten Modellen durch das Hinzufügen von modelId- und description-Eigenschaften konsistent.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}
  

Änderungen am Kopiermodell

Das Aufrufmuster für das Kopiermodell bleibt unverändert:

  • Autorisieren Sie den Kopiervorgang mit der Zielressource, die authorizeCopy aufruft. Jetzt eine POST-Anforderung.
  • Übermitteln Sie die Autorisierung an die Quellressource, um das Modell zu kopieren, das copyTo aufruft.
  • Rufen Sie den zurückgegebenen Vorgang ab, um den erfolgreichen Abschluss des Vorgangs zu überprüfen.

Die einzigen Änderungen an der Kopiermodellfunktion sind:

  • Die HTTP-Aktion für authorizeCopy ist jetzt eine POST-Anforderung.
  • Die Autorisierungsnutzdaten enthalten alle Informationen, die zum Übermitteln der Kopieranforderung erforderlich sind.

Autorisieren Sie die Kopie

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Verwenden Sie den Antworttext der Autorisierungsaktion, um die Anforderung für die Kopie zu erstellen.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

Änderungen an Listenmodellen

Listenmodelle wurden erweitert, um jetzt vordefinierte und benutzerdefinierte Modelle zurückzugeben. Alle vordefinierten Modellnamen beginnen mit prebuilt-. Nur Modelle mit dem Status „Erfolgreich“ werden zurückgegeben. Informationen zum Auflisten von Modellen, die entweder fehlerhaft oder in Bearbeitung sind, finden Sie unter Auflisten von Vorgängen.

Beispielanforderung für Listenmodelle

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

Änderung zum Abrufen des Modells

Da „get model“ jetzt auch vordefinierte Modelle enthält, gibt der GET-Vorgang ein docTypes-Wörterbuch zurück. Jeder Dokumenttyp wird durch seinen Namen, eine optionale Beschreibung, ein Feldschema und eine optionale Feldkonfidenz beschrieben. Das Feldschema beschreibt die Liste der Felder, die möglicherweise mit dem Dokumenttyp zurückgegeben werden.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

Neuer Vorgang zum Abrufen von Informationen

Der info-Vorgang für den Dienst gibt die Anzahl der benutzerdefinierten Modelle und den Grenzwert für benutzerdefinierte Modelle zurück.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

Beispiel für eine Antwort

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

Nächste Schritte

In diesem Migrationshandbuch haben Sie erfahren, wie Sie ein Upgrade für Ihre vorhandene Anwendung zur Formularerkennung für die Verwendung der v3.0-APIs durchführen.