[ai-form-recognizer] Prepare release 4.0.0-beta.4 (#22140)
* Fixed identity document sample * Added a couple of lines to the CHANGELOG * Removed caption/footnotes. * Update README * Update migration guide. * Added missing model to README * Prep changelog for release. * Added even more deprecation notices to doc strings. * Added a simple check for the existence of paragraphs. * Fixed bizarre changelog error * Fixed ci.yml
This commit is contained in:
Will Temple
GitHub
Родитель
0a876d1546
Коммит
a027f18338
|
|
@ -1,13 +1,13 @@
|
|||
# Release History
|
||||
|
||||
## 4.0.0-beta.4 (Unreleased)
|
||||
## 4.0.0-beta.4 (2022-06-07)
|
||||
|
||||
### Features Added
|
||||
|
||||
- Updated the SDK to use the latest preview version of the Form Recognizer service: `2022-06-30-preview`.
|
||||
- Added `caption` and `footnotes` properties to the `DocumentTable` type. These properties represent an optional caption and footnotes (as `DocumentCaption` and `DocumentFootnote`) that were attached to extracted tables in the input documents.
|
||||
- Added a `paragraphs` property to the `AnalyzeResult` type and a new `DocumentParagraph` type. This property represents the paragraph structure of the input document's text.
|
||||
- Documents may now contain a `DocumentAddressField` type, which has an object with several fields related to physical addresses, such as `streetAddress`, `city`, and `state` as its value. This field is identified by the value `"address"` in the `kind` field.
|
||||
- Added a `kind` field to `DocumentPage`. For now, the only supported value of this field is `"document"`. In the future, other page kinds may be added, indicating different dispositions of the extracted page elements.
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
|
|
@ -15,12 +15,10 @@
|
|||
- [**DEPRECATION**] Deprecated `beginExtractLayout`, `beginExtractGeneralDocument`, and `beginReadDocument`. In a future version (prior to a stable release), these methods will be removed, and `beginAnalyzeDocument` will be enhanced to provide the same restricted types.
|
||||
- Renamed the `beginCopyModel` method of `DocumentModelAdministrationClient` to `beginCopyModelTo`. [#20775](https://github.com/Azure/azure-sdk-for-js/pull/20775)
|
||||
- Renamed `BoundingRegion#boundingBox` to `BoundingRegion#polygon`, as the service may now provide arbitrary, polygonal bounding areas rather than just rectangles.
|
||||
- The polygon is represented as an array of `Point2D`, clockwise from the left, -180 degrees inclusive.
|
||||
- Removed the `entities` property from the `AnalyzeResult` type. This field may be reintroduced in a future version, but service API version `2022-06-30-preview` no longer returns this field.
|
||||
- Renamed the `languageCode` property in the `DocumentLanguage` type to `locale`.
|
||||
|
||||
### Bugs Fixed
|
||||
|
||||
### Other Changes
|
||||
- Made the `angle`, `height`, `lines`, `unit`, `width`, and `words` properties of `DocumentPage` optional, as not all page kinds are guaranteed to support these fields.
|
||||
|
||||
## 4.0.0-beta.3 (2022-02-10)
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
In major version 4, this package introduces a full redesign of the Azure Form Recognizer client library. To leverage features of the newest Form Recognizer service API (version "2021-09-30-preview" and newer), the new SDK is required, and application code must be changed to use the new clients. Similarly, the new major version 4 of the client library cannot be used to communicate with version 2.1 of the service API. To summarize:
|
||||
|
||||
- Version 3 of the `@azure/ai-form-recognizer` package _only_ supports Form Recognizer service API version 2.1, and will not receive support for newer (date-based) versions of Form Recognizer.
|
||||
- Version 4 (beta) of the package supports service API version "2021-09-30-preview", and future releases of this major version will support newer service API versions as well.
|
||||
- Version 4 (beta) of the package supports service API version "2022-06-30-preview", and future releases of this major version will support newer service API versions as well.
|
||||
|
||||
This document provides instructions for updating your application code to the new major version 4 of the SDK client library. In this document the examples provided use TypeScript to provide type information, but all runtime behavior changes naturally apply to plain JavaScript as well.
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ To avoid migrating an application all at once, major version 3 may be installed
|
|||
"dependencies": {
|
||||
...,
|
||||
"@azure/ai-form-recognizer": "^3.2.0",
|
||||
"@azure/ai-form-recognizer-beta": "npm:@azure/ai-form-recognizer@4.0.0-beta.2"
|
||||
"@azure/ai-form-recognizer-beta": "npm:@azure/ai-form-recognizer@4.0.0-beta.4"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -31,7 +31,7 @@ With this configuration, imports from `"@azure/ai-form-recognizer"` will import
|
|||
...,
|
||||
"dependencies": {
|
||||
...,
|
||||
"@azure/ai-form-recognizer": "4.0.0-beta.2",
|
||||
"@azure/ai-form-recognizer": "4.0.0-beta.4",
|
||||
"@azure/ai-form-recognizer-v3": "npm:@azure/ai-form-recognizer@^3.2.0"
|
||||
}
|
||||
}
|
||||
|
|
@ -80,9 +80,9 @@ The following table explores several type names from the previous (v3.x) SDK and
|
|||
| `AccountProperties` | `GetInfoResponse` | Interface | All properties replaced with `customDocumentModels`, which itself has `count` and `limit` denoting the number of models in the resource and the maximum allowable, respectively. |
|
||||
| `CopyAuthorization` | `CopyAuthorization` (no change) | Interface | `modelId` was renamed `targetModelId`, `resourceId` renamed `targetResourceId`, `resourceRegion` renamed `targetResourceRegion` and `expiresOn` renamed `expirationDateTime`. |
|
||||
|
||||
### `AnalyzeResult`, `GenericDocumentResult`, and `LayoutResult` vs. `RecognizedFormArray` and `FormPageArray`
|
||||
### `AnalyzeResult`, `GeneralDocumentResult`, and `LayoutResult` vs. `RecognizedFormArray` and `FormPageArray`
|
||||
|
||||
In the previous SDK, the analysis operations `beginRecognizeCustomForms` (as well as all of the prebuilt methods such as `beginRecognizeReceipts`) and `beginRecognizeContent` produced arrays of `RecognizedForm` and `FormPage` (respectively). Those types represented extracted structured documents and extracted page elements. However, in the new SDK, all of these methods as well as the new `beginExtractGenericDocument` method produce objects that have fields for `pages`, `tables`, `documents`, and more.
|
||||
In the previous SDK, the analysis operations `beginRecognizeCustomForms` (as well as all of the prebuilt methods such as `beginRecognizeReceipts`) and `beginRecognizeContent` produced arrays of `RecognizedForm` and `FormPage` (respectively). Those types represented extracted structured documents and extracted page elements. However, in the new SDK, all of these methods as well as the new `beginExtractGeneralDocument` method produce objects that have fields for `pages`, `tables`, `documents`, and more.
|
||||
|
||||
The fundamental type that represents the result of an analysis operation is `AnalyzeResult`:
|
||||
|
||||
|
|
@ -142,16 +142,16 @@ export interface AnalyzeResult<Document = AnalyzedDocument> {
|
|||
}
|
||||
```
|
||||
|
||||
This type is the result of prebuilt/custom model analysis using `beginAnalyzeDocuments`. The other two analysis methods produce related (but not the same) types:
|
||||
This type is the result of prebuilt/custom model analysis using `beginAnalyzeDocument`. The other two analysis methods produce related (but not the same) types:
|
||||
|
||||
- `beginExtractLayout` produces a reduced "subtype" called `LayoutResult` that only has `pages`, `tables`, and `styles` (since these are the only fields produced by the prebuilt layout model).
|
||||
- `beginExtractGenericDocument` produces a type called `GenericDocumentResult` that has all of the fields of `LayoutResult` and additionally `entities` and `keyValuePairs` (again, as these are the only five fields produced by the prebuilt generic document model).
|
||||
- `beginExtractGeneralDocument` produces a type called `GeneralDocumentResult` that has all of the fields of `LayoutResult` and additionally `entities` and `keyValuePairs` (again, as these are the only five fields produced by the prebuilt general document model).
|
||||
|
||||
**Notice** that the _relationship between data types has changed_. Whereas `tables` were previously a property of `FormPage` (in other words, every table could be associated to only a single page), they are now properties of the `AnalyzeResult` (meaning that tables can potentially span multiple pages). The same is true for the relationship between `pages` and `documents`. Previously, a `RecognizedForm` (now `AnalyzedDocument`) had a `pages` property, now `pages` is a property of the `AnalyzeResult` and not nested underneath its `documents`. This reflects the fact that in the newest Form Recognizer service APIs, multiple documents may appear on a single page. Additionally, there may be pages that have no documents within, and those pages are now representable in the SDK.
|
||||
|
||||
Compare the following samples:
|
||||
|
||||
- `beginAnalyzeDocuments` vs. `beginRecognizeCustomForms`:
|
||||
- `beginAnalyzeDocument` vs. `beginRecognizeCustomForms`:
|
||||
|
||||
Previous (3.2.0):
|
||||
|
||||
|
|
@ -164,12 +164,12 @@ Compare the following samples:
|
|||
const forms: RecognizedForm[] = await poller.pollUntilDone();
|
||||
```
|
||||
|
||||
Current (4.0.0-beta.2):
|
||||
Current (4.0.0-beta.4):
|
||||
|
||||
```typescript
|
||||
const client = new DocumentAnalysisClient(...);
|
||||
|
||||
const poller = await client.beginAnalyzeDocuments("<model ID>", input);
|
||||
const poller = await client.beginAnalyzeDocument("<model ID>", input);
|
||||
|
||||
const result: AnalyzeResult = await poller.pollUntilDone();
|
||||
|
||||
|
|
@ -183,6 +183,8 @@ Compare the following samples:
|
|||
|
||||
- `beginExtractLayout` vs. `beginRecognizeContent`:
|
||||
|
||||
**Deprecation Warning ⚠️**: The `beginExtractLayout` method of SDK version `4.0.0-beta` is deprecated and will be replaced prior to a stable release of version 4.0.0. Please see [the deprecation notice in the README](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/README.md#beginextractlayout-deprecation) for more information.
|
||||
|
||||
Previous (3.2.0):
|
||||
|
||||
```typescript
|
||||
|
|
@ -199,7 +201,7 @@ Compare the following samples:
|
|||
}
|
||||
```
|
||||
|
||||
Current (4.0.0-beta.2):
|
||||
Current (4.0.0-beta.4):
|
||||
|
||||
```typescript
|
||||
const client = new DocumentAnalysisClient(...);
|
||||
|
|
@ -233,10 +235,10 @@ if (table.boundingBox) {
|
|||
}
|
||||
```
|
||||
|
||||
Current (4.0.0-beta.2):
|
||||
Current (4.0.0-beta.4):
|
||||
|
||||
```typescript
|
||||
// Now, tables were accessed through `AnalyzeResult`.
|
||||
// Now, tables are accessed through `AnalyzeResult`.
|
||||
const table: FormTable = result.tables[0];
|
||||
|
||||
for (const region of table.boundingRegions ?? []) {
|
||||
|
|
@ -249,29 +251,29 @@ for (const region of table.boundingRegions ?? []) {
|
|||
|
||||
## Migrating from `FormRecognizerClient` to `DocumentAnalysisClient`
|
||||
|
||||
The `DocumentAnalysisClient` class, used for all analysis operations (layout, generic document, and custom/prebuilt models), has replaced `FormRecognizerClient` (which has been removed). The constructor signature is the same, but two new options have been introduced to the client constructor:
|
||||
The `DocumentAnalysisClient` class, used for all analysis operations (layout, general document, and custom/prebuilt models), has replaced `FormRecognizerClient` (which has been removed). The constructor signature is the same, but two new options have been introduced to the client constructor:
|
||||
|
||||
- `apiVersion`, which allows the application to specify the version of the Form Recognizer service API to use (the default is the newest compatible version).
|
||||
- `stringIndexType`, which configures the units used to compute string indexes and offsets (this option defaults to UTF-16 code units, and it should not be set without a very good reason).
|
||||
|
||||
The previous `FormRecognizerClient` class and new `DocumentAnalysisClient` class have no methods in common. The new class only has three methods in total. They are:
|
||||
|
||||
- `beginAnalyzeDocuments`, which replaces all of the following:
|
||||
- `beginAnalyzeDocument`, which replaces all of the following:
|
||||
- `beginRecognizeCustomForms` and `beginRecognizeCustomFormsFromUrl`
|
||||
- `beginRecognizeReceipts` and `beginRecognizeReceiptsFromUrl`
|
||||
- `beginRecognizeBusinessCards` and `beginRecognizeBusinessCardsFromUrl`
|
||||
- `beginRecognizeInvoices` and `beginRecognizeInvoicesFromUrl`
|
||||
- `beginRecognizeIdentityDocuments` and `beginRecognizeIdentityDocumentsFromUrl`
|
||||
- `beginExtractLayout`, which replaces `beginRecognizeContent` and `beginRecognizeContentFromUrl`
|
||||
- `beginExtractGenericDocument`, which is new, and provides similar functionality to unlabeled custom models from the previous SDK without the need to train a model. Please refer to [the `extractGenericDocument` sample for an example of using this new method](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4-beta/typescript/src/extractGeneralDocument.ts), as it is not quite the same as using an unlabeled custom model.
|
||||
- `beginExtractGeneralDocument`, which is new, and provides similar functionality to unlabeled custom models from the previous SDK without the need to train a model. Please refer to [the `extractGeneralDocument` sample for an example of using this new method](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4-beta/typescript/src/extractGeneralDocument.ts), as it is not quite the same as using an unlabeled custom model.
|
||||
|
||||
All of these methods produce `AnalyzeResult`, `LayoutResult`, and `GenericDocumentResult` types respectively. Please see the section above about these types for more information.
|
||||
All of these methods produce `AnalyzeResult`, `LayoutResult`, and `GeneralDocumentResult` types respectively. Please see the section above about these types for more information.
|
||||
|
||||
_\* Unlabeled custom models are no longer supported in version 4.x of the Form Recognizer SDK, to continue using unlabeled custom models, please continue to use version 3.x, but be aware that the feature is deprecated and future releases of the Form Recognizer service and SDK will not support it._
|
||||
|
||||
### URL Inputs
|
||||
|
||||
In the previous v3.x SDK, to provide a publicly-accessible URL as an input to an analysis operation, the application used a method with a `-FromUrl` suffix. For example, `beginRecognizeReceiptsFromUrl`. In the new SDK, however, there is only a single unified method signature. If a `string` is given as the input, then the string will be treated as a URL. Otherwise, it will be treated as a binary request body (such as a stream or buffer). Compare the following samples using `beginRecognizeCustomForms` and `beginAnalyzeDocuments`:
|
||||
In the previous v3.x SDK, to provide a publicly-accessible URL as an input to an analysis operation, the application used a method with a `-FromUrl` suffix. For example, `beginRecognizeReceiptsFromUrl`. In the new SDK, however, there is only a single unified method signature. If a `string` is given as the input, then the string will be treated as a URL. Otherwise, it will be treated as a binary request body (such as a stream or buffer). Compare the following samples using `beginRecognizeCustomForms` and `beginAnalyzeDocument`:
|
||||
|
||||
Previous (3.2.0):
|
||||
|
||||
|
|
@ -283,25 +285,27 @@ const url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/f
|
|||
const poller = await client.beginRecognizeCustomFormsFromUrl("<model ID>", url);
|
||||
```
|
||||
|
||||
Current (4.0.0-beta.2):
|
||||
Current (4.0.0-beta.4):
|
||||
|
||||
```typescript
|
||||
const client = new DocumentAnalysisClient(...);
|
||||
const url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/identityDocument/license.jpg";
|
||||
|
||||
// Now, the same method may be used as for streams and buffers.
|
||||
const poller = await client.beginAnalyzeDocuments("<model ID>", url);
|
||||
const poller = await client.beginAnalyzeDocument("<model ID>", url);
|
||||
```
|
||||
|
||||
### Prebuilt Models
|
||||
|
||||
In the previous v3.x SDK packages, using a prebuilt model required using a method dedicated to that model. In the new v4.x SDK, however, all prebuilt models also utilize the same `beginAnalyzeDocuments` method as custom forms. There are two ways to use a prebuilt model with `beginAnalyzeDocuments` in the new SDK. They are:
|
||||
In the previous v3.x SDK packages, using a prebuilt model required using a method dedicated to that model. In the new v4.x SDK, however, all prebuilt models also utilize the same `beginAnalyzeDocument` method as custom forms. There are two ways to use a prebuilt model with `beginAnalyzeDocument` in the new SDK. They are:
|
||||
|
||||
1. Using a `DocumentModel`, which is a data structure that provides a strong, associated type for the prebuilt output and that converts its fields into a "camelCase" JavaScript naming convention.
|
||||
2. Using the prebuilt model's ID (same as a custom model), which will produce an `AnalyzeResult` with no specific type for the prebuilt model, exactly as if the prebuilt model were a custom model (prebuilt models are simply custom models trained and tested by the Form Recognizer team).
|
||||
|
||||
We recommend using the `DocumentModel` approach (#1), as it provides the best type-safety for TypeScript users and the most idiomatic representation of the data at runtime. Compare the following three samples that show the differences using a receipt document:
|
||||
|
||||
**Deprecation Warning ⚠️**: `PrebuiltModels` is deprecated as of version `4.0.0-beta.4` and will be replaced prior to a stable release of version 4.0.0. Please see [the deprecation notice in the README](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/README.md#prebuiltmodels-deprecation) for more information.
|
||||
|
||||
Previous (3.2.0):
|
||||
|
||||
```typescript
|
||||
|
|
@ -321,7 +325,7 @@ const [receipt] = await poller.pollUntilDone();
|
|||
const receiptType: string = (receipt.fields["ReceiptType"] as FormStringField)?.value ?? "<unknown>";
|
||||
```
|
||||
|
||||
Current (4.0.0-beta.2), using the `DocumentModel`:
|
||||
Current (4.0.0-beta.4), using the `DocumentModel`:
|
||||
|
||||
```typescript
|
||||
// We need to import `PrebuiltModels`, which holds the prebuilt `DocumentModel` data structures
|
||||
|
|
@ -332,7 +336,7 @@ const url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/f
|
|||
|
||||
// Passing the `PrebuiltModels.Receipt` document model will allow TypeScript to infer a stronger type for the output,
|
||||
// and it will be validated against the model's schema as well as converted to use "camelCase" property names.
|
||||
const poller = await client.beginAnalyzeDocuments(PrebuiltModels.Receipt, url);
|
||||
const poller = await client.beginAnalyzeDocument(PrebuiltModels.Receipt, url);
|
||||
|
||||
const { documents: [receipt] } = await poller.pollUntilDone();
|
||||
|
||||
|
|
@ -343,7 +347,7 @@ const { documents: [receipt] } = await poller.pollUntilDone();
|
|||
const receiptType: string = receipt.fields.receiptType?.value ?? "<unknown>";
|
||||
```
|
||||
|
||||
Current (4.0.0-beta.2), using the model ID:
|
||||
Current (4.0.0-beta.4), using the model ID:
|
||||
|
||||
```typescript
|
||||
import { DocumentAnalysisClient, DocumentStringField } from "@azure/ai-form-recognizer";
|
||||
|
|
@ -353,7 +357,7 @@ const url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/f
|
|||
|
||||
// The prebuilt receipt model's ID is "prebuilt-receipt". When passed this way (rather than using the DocumentModel), it
|
||||
// is functionally the same as a custom model ID.
|
||||
const poller = await client.beginAnalyzeDocuments("prebuilt-receipt", url);
|
||||
const poller = await client.beginAnalyzeDocument("prebuilt-receipt", url);
|
||||
|
||||
const { documents: [receipt] } = await poller.pollUntilDone();
|
||||
|
||||
|
|
@ -362,7 +366,7 @@ const { documents: [receipt] } = await poller.pollUntilDone();
|
|||
const receiptType: string = (receipt.fields["ReceiptType"] as DocumentStringField)?.value ?? "<unknown>";
|
||||
```
|
||||
|
||||
**Note**: The prebuilt layout and generic document models can also be used with `beginAnalyzeDocuments` using their model IDs. They do not have `DocumentModel` data structures (as they do not produce `documents` in the result), but their model IDs (`"prebuilt-layout"` and `"prebuilt-document"` respectively) may be used. They will produce only the fields that they support and that would exist if used with their dedicated methods (the layout model will only produce `pages`, `tables`, and `styles`, and the generic document model will additionally produce `keyValuePairs` and `entities`), and the `documents` field will be empty.
|
||||
**Note**: The prebuilt layout and general document models can also be used with `beginAnalyzeDocument` using their model IDs. They do not have `DocumentModel` data structures (as they do not produce `documents` in the result), but their model IDs (`"prebuilt-layout"` and `"prebuilt-document"` respectively) may be used. They will produce only the fields that they support and that would exist if used with their dedicated methods (the layout model will only produce `pages`, `tables`, and `styles`, and the general document model will additionally produce `keyValuePairs` and `entities`), and the `documents` field will be empty.
|
||||
|
||||
## Migrating from `FormTrainingClient` to `DocumentModelAdministrationClient`
|
||||
|
||||
|
|
@ -436,7 +440,7 @@ if (model.trainingDocuments) {
|
|||
}
|
||||
```
|
||||
|
||||
Current (4.0.0-beta.2):
|
||||
Current (4.0.0-beta.4):
|
||||
|
||||
```typescript
|
||||
const client = new DocumentModelAdministrationClient(...);
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Azure Cognitive Services [Form Recognizer](https://azure.microsoft.com/services/
|
|||
|
||||
#### **_Breaking Change Advisory_ ⚠️**
|
||||
|
||||
In version 4 (currently beta), this package introduces a full redesign of the Azure Form Recognizer client library. To leverage features of the newest Form Recognizer service API (version "2022-01-30-preview" and newer), the new SDK is required, and application code must be changed to use the new clients. Please see the [Migration Guide](https://github.com/azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/MIGRATION-v3_v4.md) for detailed instructions on how to update application code from version 3.x of the Form Recognizer SDK to the new version (4.x). Additionally, the [CHANGELOG](https://github.com/azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/CHANGELOG.md) contains an outline of the changes. This package targets Azure Form Recognizer service API version `2022-01-30-preview` and newer. To continue to use Form Recognizer API version 2.1, please use major version 3 of the client package (`@azure/ai-form-recognizer@^3.2.0`).
|
||||
In version 4 (currently beta), this package introduces a full redesign of the Azure Form Recognizer client library. To leverage features of the newest Form Recognizer service API (version "2022-06-30-preview" and newer), the new SDK is required, and application code must be changed to use the new clients. Please see the [Migration Guide](https://github.com/azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/MIGRATION-v3_v4.md) for detailed instructions on how to update application code from version 3.x of the Form Recognizer SDK to the new version (4.x). Additionally, the [CHANGELOG](https://github.com/azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/CHANGELOG.md) contains an outline of the changes. This package targets Azure Form Recognizer service API version `2022-06-30-preview` and newer. To continue to use Form Recognizer API version 2.1, please use major version 3 of the client package (`@azure/ai-form-recognizer@^3.2.0`).
|
||||
|
||||
### Install the `@azure/ai-form-recognizer` Package
|
||||
|
||||
|
|
@ -233,6 +233,9 @@ As an alternative to providing a readable stream, a publicly-accessible URL can
|
|||
|
||||
### Extract Layout
|
||||
|
||||
<a id="beginextractlayout-deprecation"></a>
|
||||
**Deprecation Warning** ⚠️: The built in `beginExtractLayout` method is deprecated as of version `4.0.0-beta.4`. Prior to a stable release of version 4.0.0, we will remove it and provide a solution that uses the `beginAnalyzeDocument` method instead. This will align the `"prebuilt-layout"` model with the other prebuilt models, enabling us to continue to provide timely updates and ensure stability as the number of supported prebuilt models increases and as their capabilities are enhanced.
|
||||
|
||||
The `beginExtractLayout` method extracts only the basic elements of the document, such as pages, (which consist of text words/lines and selection marks), tables, and visual text styles along with their bounding regions and spans within the text content of the input documents.
|
||||
|
||||
```javascript
|
||||
|
|
@ -272,6 +275,9 @@ _Note_: you may also use the `beginAnalyzeDocument` method to extract layout inf
|
|||
|
||||
### Extract General Document
|
||||
|
||||
<a id="beginextractgeneraldocument-deprecation"></a>
|
||||
**Deprecation Warning** ⚠️: The built in `beginExtractGeneralDocument` method is deprecated as of version `4.0.0-beta.4`. Prior to a stable release of version 4.0.0, we will remove it and provide a solution that uses the `beginAnalyzeDocument` method instead. This will align the `"prebuilt-document"` model with the other prebuilt models, enabling us to continue to provide timely updates and ensure stability as the number of supported prebuilt models increases and as their capabilities are enhanced.
|
||||
|
||||
The `beginExtractGeneralDocument` method extracts information about key-value pairs and entities in addition to the properties produced by the layout extraction method. This prebuilt (general) document model provides similar functionality to the custom models trained without label information in previous iterations of the Form Recognizer service, but it is now provided as a prebuilt model that works with a wide variety of documents.
|
||||
|
||||
```javascript
|
||||
|
|
@ -326,6 +332,9 @@ _Note_: you may also use the `beginAnalyzeDocument` method to extract general do
|
|||
|
||||
### Read Document
|
||||
|
||||
<a id="beginreaddocument-deprecation"></a>
|
||||
**Deprecation Warning** ⚠️: The built in `beginReadDocument` method is deprecated as of version `4.0.0-beta.4`. Prior to a stable release of version 4.0.0, we will remove it and provide a solution that uses the `beginAnalyzeDocument` method instead. This will align the `"prebuilt-document"` model with the other prebuilt models, enabling us to continue to provide timely updates and ensure stability as the number of supported prebuilt models increases and as their capabilities are enhanced.
|
||||
|
||||
```javascript
|
||||
const { DocumentAnalysisClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");
|
||||
const fs = require("fs");
|
||||
|
|
@ -391,10 +400,17 @@ _Note_: you may also use the `beginAnalyzeDocument` method to read document info
|
|||
|
||||
The `beginAnalyzeDocument` method also supports extracting fields from certain types of common documents such as receipts, invoices, business cards, and identity documents using prebuilt models provided by the Form Recognizer service. The prebuilt models may be provided either as model ID strings (the same as custom document models) or using a `DocumentModel` object. When using a `DocumentModel`, the Form Recognizer SDK for JavaScript provides a much stronger TypeScript type for the resulting extracted documents based on the model's schema, and it will be converted to use JavaScript naming conventions.
|
||||
|
||||
<a id="prebuiltmodels-deprecation"></a>
|
||||
**Deprecation Warning** ⚠️: The built in `PrebuiltModels` are deprecated as of version `4.0.0-beta.4`. Prior to a stable release of version 4.0.0, we will replace `PrebuiltModels` with an out-of-tree solution that provides the same strongly-typed functionality. This will enable us to continue to provide timely updates and ensure stability as the number of supported prebuilt models increases and as their capabilities are enhanced.
|
||||
|
||||
For example, the following code shows how to use `PrebuiltModels.Receipt` to extract a strongly-typed receipt object from an input.
|
||||
|
||||
```javascript
|
||||
const { DocumentAnalysisClient, PrebuiltModels, AzureKeyCredential } = require("@azure/ai-form-recognizer");
|
||||
const {
|
||||
DocumentAnalysisClient,
|
||||
PrebuiltModels,
|
||||
AzureKeyCredential,
|
||||
} = require("@azure/ai-form-recognizer");
|
||||
|
||||
const fs = require("fs");
|
||||
|
||||
|
|
@ -409,12 +425,14 @@ async function main() {
|
|||
|
||||
// The PrebuiltModels.Receipt `DocumentModel` encodes both the model ID and a stronger return type for the operation
|
||||
const poller = await client.beginAnalyzeDocument(PrebuiltModels.Receipt, readStream, {
|
||||
onProgress: ({status}) => {
|
||||
onProgress: ({ status }) => {
|
||||
console.log(`status: ${status}`);
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
const { documents: [receiptDocument] } = await poller.pollUntilDone();
|
||||
const {
|
||||
documents: [receiptDocument],
|
||||
} = await poller.pollUntilDone();
|
||||
|
||||
// The fields of the document constitute the extracted receipt data.
|
||||
const receipt = receiptDocument.fields;
|
||||
|
|
@ -449,11 +467,15 @@ Alternatively, as mentioned above, instead of using `PrebuiltDocuments.Receipt`,
|
|||
|
||||
You are not limited to receipts! There are a few prebuilt models to choose from, with more on the way. Each prebuilt model has its own set of supported fields:
|
||||
|
||||
- Receipts, using `PrebuiltModels.Receipt` or the prebuilt receipt model ID `"prebuilt-receipt"` (see [the supported fields of the receipt model](https://aka.ms/azsdk/formrecognizer/receiptfieldschema)).
|
||||
- Business cards, using `PrebuiltModels.BusinessCard` or its model ID `"prebuilt-businessCard"` (see [the supported fields of the business card model](https://aka.ms/azsdk/formrecognizer/businesscardfieldschema)).
|
||||
- Invoices, using `PrebuiltModels.Invoice` or its model ID `"prebuilt-invoice"` (see [the supported fields of the invoice model](https://aka.ms/azsdk/formrecognizer/invoicefieldschema)).
|
||||
- Identity Documents (such as driver licenses and passports), using `PrebuiltModels.IdentityDocument` or its model ID `"prebuilt-idDocument"` (see [the supported fields of the identity document model](https://aka.ms/azsdk/formrecognizer/iddocumentfieldschema)).
|
||||
- W2 Tax Forms (United States), using `PrebuiltModels.TaxUsW2` or its model ID `"prebuilt-tax.us.w2"` (see [the supported fields of the W2 model](https://aka.ms/azsdk/formrecognizer/taxusw2fieldschema)).
|
||||
- Receipts, using `PrebuiltModels.Receipt` or the prebuilt receipt model ID `"prebuilt-receipt"`.
|
||||
- Business cards, using `PrebuiltModels.BusinessCard` or its model ID `"prebuilt-businessCard"`.
|
||||
- Invoices, using `PrebuiltModels.Invoice` or its model ID `"prebuilt-invoice"`.
|
||||
- Identity Documents (such as driver licenses and passports), using `PrebuiltModels.IdentityDocument` or its model ID `"prebuilt-idDocument"`.
|
||||
- W2 Tax Forms (United States), using `PrebuiltModels.TaxUsW2` or its model ID `"prebuilt-tax.us.w2"`.
|
||||
- Health Insurance Cards (United States), using `PrebuiltModels.HealthInsuranceCardUs` or its model ID `"prebuilt-healthInsuranceCard.us"`.
|
||||
- Vaccination Cards (currently supports US COVID-19 vaccination cards), using `PrebuiltModels.VaccinationCard` or its model ID `"prebuilt-vaccinationCard"`.
|
||||
|
||||
For information about the fields of these models, see [the service's documentation of the available prebuilt models](https://aka.ms/azsdk/formrecognizer/models).
|
||||
|
||||
The fields of all prebuilt document models may also be accessed programmatically using the `getModel` method (by their model IDs) of `DocumentModelAdministrationClient` and inspecting the `docTypes` field in the result.
|
||||
|
||||
|
|
|
|||
|
|
@ -489,10 +489,8 @@ export interface DocumentStyle {
|
|||
// @public
|
||||
export interface DocumentTable {
|
||||
boundingRegions?: BoundingRegion[];
|
||||
caption?: DocumentCaption;
|
||||
cells: DocumentTableCell[];
|
||||
columnCount: number;
|
||||
footnotes?: DocumentFootnote[];
|
||||
rowCount: number;
|
||||
spans: DocumentSpan[];
|
||||
}
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ async function main() {
|
|||
const poller = await client.beginAnalyzeDocument(
|
||||
PrebuiltModels.IdentityDocument,
|
||||
// The form recognizer service will access the following URL to a driver license image and extract data from it
|
||||
"https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/identityDocument/license.jpg"
|
||||
"https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/identityDocument/license.png"
|
||||
);
|
||||
|
||||
const {
|
||||
|
|
|
|||
|
|
@ -356,6 +356,11 @@ export class DocumentAnalysisClient {
|
|||
}
|
||||
|
||||
/**
|
||||
* **Deprecation Warning**: This method is deprecated and will be replaced prior to a stable release of
|
||||
* `@azure/ai-form-recognizer` 4.0.0. Please see
|
||||
* [the deprecation notice](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/README.md#beginextractlayout-deprecation)
|
||||
* in the README for more information.
|
||||
*
|
||||
* Extracts only the layout (basic OCR information) from an input file. The layout result includes information about
|
||||
* the pages and their text contents, extracted tables, and identified text styles.
|
||||
*
|
||||
|
|
@ -408,7 +413,7 @@ export class DocumentAnalysisClient {
|
|||
* {@link FormRecognizerRequestBody} that will be uploaded with the request
|
||||
* @param options - optional settings for the analysis operation and poller
|
||||
* @returns a long-running operation (poller) that will eventually produce a layout result or an error
|
||||
* @deprecated will be removed in a future version (prior to a stable release)
|
||||
* @deprecated will be replaced in a future version (prior to a stable release)
|
||||
*/
|
||||
public async beginExtractLayout(
|
||||
input: string | FormRecognizerRequestBody,
|
||||
|
|
@ -428,6 +433,11 @@ export class DocumentAnalysisClient {
|
|||
}
|
||||
|
||||
/**
|
||||
* **Deprecation Warning**: This method is deprecated and will be replaced prior to a stable release of
|
||||
* `@azure/ai-form-recognizer` 4.0.0. Please see
|
||||
* [the deprecation notice](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/README.md#beginextractgeneraldocument-deprecation)
|
||||
* in the README for more information.
|
||||
*
|
||||
* Extracts general document information from an input file. The general document result includes the information from
|
||||
* layout analysis (pages, tables, and styles) as well as extracted key-value pairs and entities.
|
||||
*
|
||||
|
|
@ -490,7 +500,7 @@ export class DocumentAnalysisClient {
|
|||
* {@link FormRecognizerRequestBody} that will be uploaded with the request
|
||||
* @param options - optional settings for the analysis operation and poller
|
||||
* @returns a long-running operation (poller) that will eventually produce a general document result or an error
|
||||
* @deprecated will be removed in a future version (prior to a stable release)
|
||||
* @deprecated will be replaced in a future version (prior to a stable release)
|
||||
*/
|
||||
public async beginExtractGeneralDocument(
|
||||
input: string | FormRecognizerRequestBody,
|
||||
|
|
@ -511,6 +521,11 @@ export class DocumentAnalysisClient {
|
|||
}
|
||||
|
||||
/**
|
||||
* **Deprecation Warning**: This method is deprecated and will be replaced prior to a stable release of
|
||||
* `@azure/ai-form-recognizer` 4.0.0. Please see
|
||||
* [the deprecation notice](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/README.md#beginreaddocument-deprecation)
|
||||
* in the README for more information.
|
||||
*
|
||||
* Extracts textual information from a document such as the text contents of pages and identified written languages.
|
||||
*
|
||||
* ### Examples
|
||||
|
|
@ -562,7 +577,7 @@ export class DocumentAnalysisClient {
|
|||
* {@link FormRecognizerRequestBody} that will be uploaded with the request
|
||||
* @param options - optional settings for the analysis operation and poller
|
||||
* @returns a long-running operation (poller) that will eventually produce a read result or an error
|
||||
* @deprecated will be removed in a future version (prior to a stable release)
|
||||
* @deprecated will be replaced in a future version (prior to a stable release)
|
||||
*/
|
||||
public async beginReadDocument(
|
||||
input: string | FormRecognizerRequestBody,
|
||||
|
|
|
|||
|
|
@ -87,10 +87,6 @@ export interface DocumentTable {
|
|||
columnCount: number;
|
||||
/** Cells contained within the table. */
|
||||
cells: DocumentTableCell[];
|
||||
/** Caption associated with the table. */
|
||||
caption?: DocumentCaption;
|
||||
/** Footnotes associated with the table. */
|
||||
footnotes?: DocumentFootnote[];
|
||||
/** Bounding regions covering the table. */
|
||||
boundingRegions?: BoundingRegion[];
|
||||
/** Location of the table in the reading order concatenated content. */
|
||||
|
|
|
|||
|
|
@ -147,6 +147,11 @@ export function getMapper<M extends DocumentModel<unknown>>(
|
|||
}
|
||||
|
||||
/**
|
||||
* **Deprecation Warning**: This object, along with all of its fields, is deprecated and will be replaced prior to a
|
||||
* stable release of `@azure/ai-form-recognizer` 4.0.0. Please see
|
||||
* [the deprecation notice](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/README.md#prebuiltmodels-deprecation)
|
||||
* in the README for more information.
|
||||
*
|
||||
* Prebuilt models with well-known document types and corresponding field schemas.
|
||||
*
|
||||
* These prebuilt `DocumentModel` objects can be used with the `beginAnalyzeDocuments` method to extract documents with
|
||||
|
|
|
|||
|
|
@ -53,13 +53,6 @@ export function toDocumentTableFromGenerated(table: GeneratedDocumentTable): Doc
|
|||
...cell,
|
||||
boundingRegions: toBoundingRegions(cell.boundingRegions),
|
||||
})),
|
||||
caption: table.caption
|
||||
? { ...table.caption, boundingRegions: toBoundingRegions(table.caption?.boundingRegions) }
|
||||
: undefined,
|
||||
footnotes: table.footnotes?.map((footnote) => ({
|
||||
...footnote,
|
||||
boundingRegions: toBoundingRegions(footnote.boundingRegions),
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -82,8 +82,17 @@ matrix([[/* true, */ false]] as const, async (useAad) => {
|
|||
const filePath = path.join(ASSET_PATH, "receipt", "contoso-receipt.png");
|
||||
const stream = fs.createReadStream(filePath);
|
||||
|
||||
const poller = await client.beginExtractLayout(stream, testPollingOptions);
|
||||
const { pages } = await poller.pollUntilDone();
|
||||
const poller = await client.beginAnalyzeDocument(
|
||||
"prebuilt-layout",
|
||||
stream,
|
||||
testPollingOptions
|
||||
);
|
||||
const { pages, paragraphs } = await poller.pollUntilDone();
|
||||
|
||||
assert.ok(
|
||||
paragraphs && paragraphs.length > 0,
|
||||
`Expected non-empty paragraphs but got ${paragraphs}.`
|
||||
);
|
||||
|
||||
assert.ok(pages && pages.length > 0, `Expect no-empty pages but got ${pages}`);
|
||||
});
|
||||
|
|
|
|||
|
|
@ -8,8 +8,7 @@ trigger:
|
|||
- hotfix/*
|
||||
paths:
|
||||
include:
|
||||
- sdk/formrecognizer/ci.mgmt.yml
|
||||
- sdk/formrecognizer/ai-form-recognizer/
|
||||
- sdk/formrecognizer/
|
||||
pr:
|
||||
branches:
|
||||
include:
|
||||
|
|
@ -30,4 +29,4 @@ extends:
|
|||
ServiceDirectory: formrecognizer
|
||||
Artifacts:
|
||||
- name: azure-ai-form-recognizer
|
||||
safeName: azureaiformrecognizer
|
||||
safeName: azureaiformrecognizer
|
||||
Загрузка…
Ссылка в новой задаче