Form Recognizer v3.0-| Voorbeeld

Belangrijk

Form Recognizer REST API v3.0 worden belangrijke wijzigingen in de JSON van de REST API-aanvraag en -analyse doorgevoerd.

Form Recognizer v3.0 (preview) worden verschillende nieuwe functies en mogelijkheden toegevoegd:

In dit artikel leert u de verschillen tussen Form Recognizer v2.1 en v3.0 en hoe u over kunt gaan naar de nieuwere versie van de API.

Wijzigingen in de REST API-eindpunten

De v3.0-REST API combineert de analysebewerkingen voor lay-outanalyse, vooraf gebouwde modellen en aangepaste modellen in één paar bewerkingen door en toe te wijzen aan indelingsanalyse (vooraf gebouwde indeling) en vooraf gebouwde documentModels modelId modellen.

POST-aanvraag

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-07-30-preview

GET-aanvraag

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2021-07-30-preview

Bewerking analyseren

  • De nettolading van de aanvraag en het aanroeppatroon blijven ongewijzigd.
  • Met de bewerking Analyseren geeft u het invoerdocument en inhoudsspecifieke configuraties op. Hiermee wordt de URL van het analyseresultaat via de Operation-Location header in het antwoord.
  • Poll deze Resultaat-URL analyseren via een GET-aanvraag om de status van de analysebewerking te controleren (minimaal aanbevolen interval tussen aanvragen is 1 seconde).
  • Als de status is geslaagd, wordt de status ingesteld op geslaagd en wordt analyzeResult geretourneerd in de antwoord-body. Als er fouten optreden, wordt de status ingesteld op Mislukt en wordt er een fout geretourneerd.
Model v2.1 v3.0
Aanvraag-URL-voorvoegsel https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
🆕 algemeen document N.v.t. /documentModels/prebuilt-document:analyze
Indeling /layout/analyze /documentModels/prebuilt-layout:analyze
Aangepast /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Factuur /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Ontvangst /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Id-document /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Visitekaartje /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze

Aanvraag body analyseren

De inhoud die moet worden geanalyseerd, wordt geleverd via de aanvraag body. De URL of base64-gecodeerde gegevens kunnen gebruiker zijn om de aanvraag te maken.

Als u een openbaar toegankelijke web-URL wilt opgeven, stelt u Content-Type in op application/json   en verzendt u de volgende JSON-body:

{
  "urlSource": "{urlPath}"
}

Base64-codering wordt ook ondersteund in Form Recognizer v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Aanvullende parameters

Parameters die nog steeds worden ondersteund:

  • pagina's
  • landinstelling

Parameters worden niet meer ondersteund:

  • includeTextDetails

De nieuwe antwoordindeling is compacter en de volledige uitvoer wordt altijd geretourneerd.

Wijzigingen voor het analyseren van resultaten

Het antwoord voor analyseren is gefactoreerd naar de volgende resultaten op het hoogste niveau om meerdere pagina-elementen te ondersteunen.

  • pagina's
  • tabellen
  • keyValuePairs
  • entiteiten
  • Stijlen
  • documenten

Notitie

De analyzeResult-antwoordwijzigingen omvatten een aantal wijzigingen, zoals het omhoog verplaatsen van een eigenschap van pagina's naar een top-lever-eigenschap binnen analyzeResult.


{
// Basic analyze result metadata
"apiVersion": "2021-07-30-preview", // 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 bounding box 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": [ // Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"boundingBox": [ ... ], // Bounding box
}
],
"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
}, ...
}
}, ...
]
}



Model bouwen of trainen

Het modelobject heeft twee updates in de nieuwe API

  • modelId is nu een eigenschap die kan worden ingesteld op een model voor een voor mensen leesbare naam.
  • De naam van modelName is gewijzigd in description

De build bewerking wordt aangeroepen om een model te trainen. De nettolading van de aanvraag en het aanroeppatroon blijven ongewijzigd. Met de buildbewerking worden het model en de trainingsset opgegeven. Het resultaat wordt via de Operation-Location header in het antwoord. Poll de URL van deze modelbewerking via een GET-aanvraag om de status van de buildbewerking te controleren (minimaal aanbevolen interval tussen aanvragen is 1 seconde). In tegenstelling tot v2.1 is deze URL niet de resourcelocatie van het model. In plaats daarvan kan de model-URL worden samengesteld uit de opgegeven modelId, die ook wordt opgehaald uit de eigenschap resourceLocation in het antwoord. Als dit is gelukt, wordt de status ingesteld op succeeded en bevat het resultaat de gegevens van het aangepaste model. Als er fouten optreden, wordt de status ingesteld op failed en wordt de fout geretourneerd.

De volgende code is een voorbeeld van een build-aanvraag met behulp van een SAS-token. Let op de schuine streep bij het instellen van het voorvoegsel of mappad.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2021-09-30-preview

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

Wijzigingen in het opstellen van het model

Het opstellen van modellen is nu beperkt tot één niveau van nesten. Samengestelde modellen zijn nu consistent met aangepaste modellen met de toevoeging van modelId - en description -eigenschappen.

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

Wijzigingen in het model kopiëren

Het aanroeppatroon voor het kopieermodel blijft ongewijzigd:

  • Machtig de kopieerbewerking met de doelresource die authorizeCopy aanroept. Nu een POST-aanvraag.
  • Verzend de autorisatie naar de bronresource om het model te kopiëren dat aanroept copy-to
  • Poll de geretourneerde bewerking om te valideren dat de bewerking is voltooid

De enige wijzigingen in de functie model kopiëren zijn:

  • HTTP-actie op authorizeCopy de is nu een POST-aanvraag.
  • De nettolading voor autorisatie bevat alle informatie die nodig is om de kopieaanvraag in te dienen.

De kopie autor toestemming geven

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2021-09-30-preview
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Gebruik de antwoord-body van de geautoriseerde actie om de aanvraag voor de kopie te maken.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copy-to?api-version=2021-09-30-preview
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

Wijzigingen in lijstmodellen

Lijstmodellen zijn uitgebreid om nu vooraf gemaakte en aangepaste modellen te retourneren. Alle vooraf gebouwde modelnamen beginnen met prebuilt- . Alleen modellen met de status Geslaagd worden geretourneerd. Zie Lijstbewerkingen voor een lijst met modellen die zijn mislukt of worden uitgevoerd.

Aanvraag voor voorbeeldlijstmodellen

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2021-09-30-preview

Wijzigen om model op te halen

Omdat het get-model nu vooraf gebouwde modellen bevat, retourneert de get-bewerking een docTypes woordenlijst. Elk documenttype wordt beschreven door de naam, optionele beschrijving, veldschema en optionele veldvertrouwen. Het veldschema beschrijft de lijst met velden die mogelijk worden geretourneerd met het documenttype.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview

Nieuwe bewerking voor het op halen van gegevens

De info bewerking op de service retourneert het aantal aangepaste modellen en de limiet voor aangepaste modellen.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2021-09-30-preview

Voorbeeldantwoord

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

Volgende stappen

In deze migratiehandleiding hebt u geleerd hoe u uw bestaande Form Recognizer kunt upgraden voor het gebruik van de v3.0-API's. Gebruik de API 2.1 voor alle ga-functies en gebruik de API 3.0 voor een van de preview-functies.