Rozpoznawanie formularzy migracji do wersji 3.0 | Podgląd

Ważne

Rozpoznawanie formularzy API REST w wersji 3.0 wprowadza istotne zmiany w żądaniu interfejsu API REST i analizują dane JSON odpowiedzi.

Rozpoznawanie formularzy wersji 3.0 (wersja zapoznawcza) wprowadzono kilka nowych funkcji i możliwości:

W tym artykule poznasz różnice między wersjami Rozpoznawanie formularzy 2.1 i 3.0 oraz dowiesz się, jak przejść do nowszej wersji interfejsu API.

Zmiany w punktach końcowych interfejsu API REST

Interfejs API REST w wersji 3.0 łączy operacje analizy analizy układu, wstępnie utworzonych modeli i modeli niestandardowych w jedną parę operacji, przypisując elementy i do analizy układu (wstępnie utworzony układ) i wstępnie documentModels modelId utworzonych modeli.

Żądanie POST

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

Żądanie GET

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

Operacja analizowania

  • Ładunek żądania i wzorzec wywołania pozostają niezmienione.
  • Operacja Analizuj określa dokument wejściowy i konfiguracje specyficzne dla zawartości. Zwraca adres URL wyniku analizy za pośrednictwem Operation-Location nagłówka w odpowiedzi.
  • Sonduj ten adres URL wyniku analizy za pośrednictwem żądania GET, aby sprawdzić stan operacji analizy (minimalny zalecany interwał między żądaniami wynosi 1 sekundę).
  • Po sukcesie stan jest ustawiany na powodzenie i w treści odpowiedzi jest zwracany stan analyzeResult. Jeśli wystąpią błędy, stan zostanie ustawiony na niepowodzenie i zostanie zwrócony błąd.
Model Wersja 2.1 wersja 3.0
Prefiks adresu URL żądania https://{punkt końcowy rozpoznawania formularzy}/formrecognizer/v2.1 https://{punkt końcowy rozpoznawania formularzy}/formrecognizer
🆕 Dokument ogólny Nie dotyczy /documentModels/prebuilt-document:analyze
Układ /layout/analyze /documentModels/prebuilt-layout:analyze
Niestandardowe /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Faktura /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Otrzymania /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Dokument identyfikatora /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Wizytówka /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze

Analizowanie treści żądania

Zawartość do przeanalizowania jest dostarczana za pośrednictwem treści żądania. Użytkownikiem może być adres URL lub dane zakodowane w formacie base64, aby utworzyć żądanie.

Aby określić publicznie dostępny internetowy adres URL, ustaw typ zawartości na application/json i   wyślij następującą treść JSON:

{
  "urlSource": "{urlPath}"
}

Kodowanie Base64 jest również obsługiwane w Rozpoznawanie formularzy w wersji 3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Dodatkowe parametry

Parametry, które nadal są obsługiwane:

  • strony
  • locale

Parametry nie są już obsługiwane:

  • includeTextDetails

Nowy format odpowiedzi jest bardziej kompaktowy i zawsze zwracane są pełne dane wyjściowe.

Zmiany w celu przeanalizowania wyniku

Odpowiedź na analizę została z refaktoryzowana do następujących wyników najwyższego poziomu w celu obsługi elementów wielostronicowych.

  • strony
  • tabele
  • keyValuePairs
  • Podmioty
  • Style
  • dokumenty

Uwaga

Zmiany odpowiedzi analyzeResult obejmują szereg zmian, takich jak przejście z właściwości stron do właściwości górnej dźwigni w ramach właściwości 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
}, ...
}
}, ...
]
}



Tworzenie lub trenowanie modelu

Obiekt modelu ma dwie aktualizacje w nowym interfejsie API

  • modelId jest teraz właściwością, która może być ustawiona na modelu dla czytelnej nazwy dla człowieka.
  • Zmieniono nazwę polecenia modelName na description

Operacja build jest wywoływana w celu trenowania modelu. Ładunek żądania i wzorzec wywołania pozostają niezmienione. Operacja kompilacji określa model i zestaw danych trenowania. Zwraca wynik za pośrednictwem Operation-Location nagłówka w odpowiedzi. Sonduj ten adres URL operacji modelu za pośrednictwem żądania GET, aby sprawdzić stan operacji kompilacji (minimalny zalecany interwał między żądaniami to 1 sekunda). W przeciwieństwie do wersji 2.1 ten adres URL nie jest lokalizacją zasobu modelu. Zamiast tego adres URL modelu można skonstruować na pomocą podanego obiektu modelId, który również został pobrany z właściwości resourceLocation w odpowiedzi. Po sukcesie stan jest ustawiany na , succeeded a wynik zawiera informacje o modelu niestandardowym. Jeśli wystąpią błędy, stan jest ustawiony na failed i zwracany jest błąd.

Poniższy kod jest przykładowym żądaniem kompilacji korzystającym z tokenu SAS. Zwróć uwagę na ukośnik na końcowej ścieżce podczas ustawiania prefiksu lub ścieżki folderu.

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

Zmiany w celu redagowania modelu

Tworzenie modelu jest teraz ograniczone do pojedynczego poziomu zagnieżdżania. Złożone modele są teraz spójne z modelami niestandardowymi z dodawaniem modelId właściwości description i .

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

Zmiany modelu kopiowania

Wzorzec wywołania dla modelu kopiowania pozostaje niezmieniony:

  • Autoryzuj operację kopiowania za pomocą zasobu docelowego wywołującego authorizeCopy . Teraz żądanie POST.
  • Przesyłanie autoryzacji do zasobu źródłowego w celu skopiowania modelu wywołującego copy-to
  • Sonduj zwróconą operację, aby zweryfikować, czy operacja została pomyślnie ukończona

Jedyne zmiany w funkcji modelu kopiowania są:

  • Akcja HTTP dla authorizeCopy jest teraz żądaniem POST.
  • Ładunek autoryzacji zawiera wszystkie informacje potrzebne do przesyłania żądania kopiowania.

Autoryzowanie kopii

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

Użyj treści odpowiedzi z akcji autoryzacji, aby skonstruować żądanie dla kopii.

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

Zmiany modeli listy

Modele listy zostały rozszerzone, aby teraz zwracały wstępnie utworzone i niestandardowe modele. Wszystkie wstępnie utworzone nazwy modeli zaczynają się od prebuilt- . Zwracane są tylko modele ze stanem Powodzenie. Aby wyświetlić listę modeli, które zakończyły się niepowodzeniem lub są w toku, zobacz Wyświetlanie listy operacji.

Przykładowe żądanie modeli listy

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

Zmiana w celu uzyskania modelu

Ponieważ funkcja get model zawiera teraz wstępnie utworzone modele, operacja get zwraca docTypes słownik. Każdy typ dokumentu jest opisany za pomocą nazwy, opcjonalnego opisu, schematu pola i opcjonalnego zaufania pola. Schemat pola opisuje listę pól, które mogą być zwracane z typem dokumentu.

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

Nowa operacja get info

Operacja info w usłudze zwraca liczbę modeli niestandardowych i limit modelu niestandardowego.

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

Przykładowa odpowiedź

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

Następne kroki

W tym przewodniku migracji opisano sposób uaktualniania istniejącej aplikacji Rozpoznawanie formularzy w celu korzystania z interfejsów API w wersji 3.0. Nadal używaj interfejsu API 2.1 dla wszystkich funkcji w wersji gałęd i korzystaj z interfejsu API 3.0 dla dowolnej funkcji w wersji zapoznawczej.