Formigenkänning v3.0 | Förhandsgranska

Viktigt

Formigenkänning REST API v3.0 introducerar större ändringar i REST API begäran och analyserar JSON-svar.

Formigenkänning v3.0 (förhandsversion) introducerar flera nya funktioner:

I den här artikeln lär du dig skillnaderna mellan Formigenkänning v2.1 och v3.0 och hur du flyttar till den nyare versionen av API:et.

Ändringar i REST API slutpunkter

V3.0-REST API kombinerar analysåtgärderna för layoutanalys, fördefinierade modeller och anpassade modeller till ett enda par åtgärder genom att tilldela och documentModels till layoutanalys (förbyggd layout) och fördefinierade modelId modeller.

POST-begäran

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

GET-begäranden

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

Analysera åtgärd

  • Nyttolasten för begäran och anropsmönstret förblir oförändrade.
  • Åtgärden Analysera anger indatadokumentet och innehållsspecifika konfigurationer. Den returnerar URL:en för analysresultat via Operation-Location-huvudet i svaret.
  • Avsök denna ANALYSERA resultat-URL via en GET-begäran för att kontrollera status för analysåtgärden (minsta rekommenderade intervall mellan begäranden är 1 sekund).
  • När det har lyckats anges statusen till succeeded (lyckades) och analyzeResult returneras i svarstexten. Om fel påträffas anges statusen till Misslyckad och ett fel returneras.
Modell v2.1 v3.0
Prefix för begärande-URL https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
🆕 allmänt dokument Ej tillämpligt /documentModels/prebuilt-document:analyze
Layout /layout/analyze /documentModels/prebuilt-layout:analyze
Anpassad /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Faktura /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Mottagandet /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
ID-dokument /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Visitkort /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze

Analysera begärandetexten

Innehållet som ska analyseras tillhandahålls via begärandetexten. Antingen URL:en eller base64-kodade data kan vara användare för att skapa begäran.

Om du vill ange en offentligt tillgänglig webb-URL anger du Content-Type till application/json   och skickar följande JSON-brödtext:

{
  "urlSource": "{urlPath}"
}

Base64-kodning stöds också i Formigenkänning v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Ytterligare parametrar

Parametrar som fortfarande stöds:

  • sidor
  • locale

Parametrar stöds inte längre:

  • includeTextDetails

Det nya svarsformatet är mer kompakt och fullständiga utdata returneras alltid.

Ändringar för att analysera resultat

Analyssvar har omstrukturerats till följande toppnivåresultat för att stödja element med flera sidor.

  • sidor
  • tabeller
  • keyValuePairs
  • Enheter
  • Stilar
  • dokument

Anteckning

Svarsändringarna i analyzeResult innehåller ett antal ändringar som att flytta upp från en egenskap för sidor till en övre lever-egenskap i 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
}, ...
}
}, ...
]
}



Skapa eller träna modell

Modellobjektet har två uppdateringar i det nya API:et

  • modelId är nu en egenskap som kan anges för en modell för ett läsbart namn.
  • modelName har bytt namn till description

Åtgärden build anropas för att träna en modell. Nyttolasten för begäran och anropsmönstret förblir oförändrade. Build-åtgärden anger modell- och träningsdatauppsättningen. Den returnerar resultatet via Operation-Location-huvudet i svaret. Avsök den här modellåtgärds-URL:en via en GET-begäran för att kontrollera status för byggåtgärden (minsta rekommenderade intervall mellan begäranden är 1 sekund). Till skillnad från v2.1 är den här URL:en inte modellens resursplats. I stället kan modell-URL:en konstrueras från det angivna modelId:t, som också hämtas från resourceLocation-egenskapen i svaret. Vid lyckad status anges till succeeded och resultatet innehåller information om den anpassade modellen. Om fel påträffas anges status till failed och felet returneras.

Följande kod är ett exempel på en byggbegäran med hjälp av en SAS-token. Observera det avslutande snedstrecket när du anger prefixet eller mappsökvägen.

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/}"
  }
}

Ändringar för att skapa modell

Modellkompetenten är nu begränsad till en enda kapslingsnivå. Sammansatta modeller är nu konsekventa med anpassade modeller med tillägget av modelId egenskaperna description och .

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

Ändringar i kopieringsmodellen

Anropsmönstret för kopieringsmodellen förblir oförändrat:

  • Auktorisera kopieringsåtgärden med målresursen som anropar authorizeCopy . Nu en POST-begäran.
  • Skicka auktoriseringen till källresursen för att kopiera modellanropet copy-to
  • Avsök den returnerade åtgärden för att verifiera att åtgärden har slutförts

De enda ändringarna i kopieringsmodellfunktionen är:

  • HTTP-åtgärden på authorizeCopy är nu en POST-begäran.
  • Nyttolasten för auktorisering innehåller all information som behövs för att skicka kopieringsbegäran.

Auktorisera kopian

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

Använd svarstexten från auktorisera-åtgärden för att skapa begäran för kopian.

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"
}

Ändringar i listmodeller

Listmodeller har utökats för att nu returnera fördefinierade och anpassade modeller. Alla fördefinierade modellnamn börjar med prebuilt- . Endast modeller med statusen lyckades returneras. En lista över modeller som antingen misslyckades eller pågår finns i Liståtgärder.

Exempellista för modellbegäran

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

Ändra för att hämta modellen

Nu när get-modellen innehåller fördefinierade modeller returnerar get-åtgärden en docTypes ordlista. Varje dokumenttyp beskrivs med dess namn, valfri beskrivning, fältschema och valfritt fältförtroende. Fältschemat beskriver listan med fält som potentiellt returneras med dokumenttypen.

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

Ny åtgärd för att hämta information

Åtgärden info i tjänsten returnerar det anpassade modellantalet och den anpassade modellgränsen.

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

Exempelsvar

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

Nästa steg

I den här migreringsguiden har du lärt dig hur du uppgraderar ditt befintliga Formigenkänning att använda v3.0-API:erna. Fortsätt att använda 2.1-API:et för alla GA-funktioner och använd 3.0-API:et för någon av förhandsgranskningsfunktionerna.