Post release automated changes for formrecognizer releases (#18080)

Post release automated changes for azure-ai-form-recognizer

sdk/formrecognizer/ai-form-recognizer/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+## 4.0.0-beta.2 (Unreleased)
+
+### Features Added
+
+### Breaking Changes
+
+### Bugs Fixed
+
+### Other Changes
+
 ## 4.0.0-beta.1 (2021-10-07)
 
 This new major version beta 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. 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). The following sections contain an outline of the changes.

sdk/formrecognizer/ai-form-recognizer/package.json

@@ -3,7 +3,7 @@
   "sdk-type": "client",
   "author": "Microsoft Corporation",
   "description": "An isomorphic client library for the Azure Form Recognizer service.",
-  "version": "4.0.0-beta.1",
+  "version": "4.0.0-beta.2",
   "keywords": [
     "node",
     "azure",

sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/README.md

@@ -0,0 +1,90 @@
+---
+page_type: sample
+languages:
+  - javascript
+products:
+  - azure
+  - azure-cognitive-services
+  - azure-form-recognizer
+urlFragment: ai-form-recognizer-javascript
+---
+
+# Azure Form Recognizer client library samples for JavaScript
+
+These sample programs show how to use the JavaScript client libraries for Azure Form Recognizer in some common scenarios.
+
+| **File Name**                                           | **Description**                                                                            |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| [composeModel.js][composemodel]                         | create a composed model from several individual labeled models                             |
+| [analyzeBusinessCard.js][analyzebusinesscard]           | extract data from a business card document                                                 |
+| [analyzeDocumentByModelId.js][analyzedocumentbymodelid] | analyze a document using a model by ID                                                     |
+| [analyzeIdentityDocument.js][analyzeidentitydocument]   | extract data from an identity document                                                     |
+| [analyzeInvoice.js][analyzeinvoice]                     | extract data from an invoice document                                                      |
+| [analyzeReceipt.js][analyzereceipt]                     | extract data from a receipt document                                                       |
+| [analyzeReceiptByModelId.js][analyzereceiptbymodelid]   | use the "prebuilt-receipt" model ID to extract data from a receipt document (weakly-typed) |
+| [buildModel.js][buildmodel]                             | build a model with a single document type from a training data set                         |
+| [copyModel.js][copymodel]                               | copy a model from one resource to another                                                  |
+| [extractGenericDocument.js][extractgenericdocument]     | use the prebuilt (generic) document model to extract key-value pairs and entities          |
+| [extractLayout.js][extractlayout]                       | use the prebuilt layout model to extract basic document elements only                      |
+| [getInfo.js][getinfo]                                   | get information about the count and limit of custom models in the resource                 |
+| [getModel.js][getmodel]                                 | get information about a model by its ID                                                    |
+| [listModels.js][listmodels]                             | iterate over the models in a resource                                                      |
+
+## Prerequisites
+
+The sample programs are compatible with [LTS versions of Node.js](https://nodejs.org/about/releases/).
+
+You need [an Azure subscription][freesub] and the following Azure resources to run these sample programs:
+
+- [Azure Cognitive Services account][createinstance_azurecognitiveservicesaccount]
+
+Samples retrieve credentials to access the service endpoint from environment variables. Alternatively, edit the source code to include the appropriate credentials. See each individual sample for details on which environment variables/credentials it requires to function.
+
+Adapting the samples to run in the browser may require some additional consideration. For details, please see the [package README][package].
+
+## Setup
+
+To run the samples using the published version of the package:
+
+1. Install the dependencies using `npm`:
+
+```bash
+npm install
+```
+
+2. Edit the file `sample.env`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `sample.env` to just `.env`. The sample programs will read this file automatically.
+
+3. Run whichever samples you like (note that some samples may require additional setup, see the table above):
+
+```bash
+node composeModel.js
+```
+
+Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform):
+
+```bash
+npx cross-env FORM_RECOGNIZER_ENDPOINT="<form recognizer endpoint>" FORM_RECOGNIZER_API_KEY="<form recognizer api key>" PURCHASE_ORDER_SUPPLIES_SAS_URL="<purchase order supplies sas url>" PURCHASE_ORDER_EQUIPMENT_SAS_URL="<purchase order equipment sas url>" PURCHASE_ORDER_FURNITURE_SAS_URL="<purchase order furniture sas url>" PURCHASE_ORDER_CLEANING_SUPPLIES_SAS_URL="<purchase order cleaning supplies sas url>" node composeModel.js
+```
+
+## Next Steps
+
+Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients.
+
+[composemodel]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/composeModel.js
+[analyzebusinesscard]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeBusinessCard.js
+[analyzedocumentbymodelid]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeDocumentByModelId.js
+[analyzeidentitydocument]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeIdentityDocument.js
+[analyzeinvoice]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeInvoice.js
+[analyzereceipt]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeReceipt.js
+[analyzereceiptbymodelid]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeReceiptByModelId.js
+[buildmodel]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/buildModel.js
+[copymodel]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/copyModel.js
+[extractgenericdocument]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/extractGenericDocument.js
+[extractlayout]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/extractLayout.js
+[getinfo]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/getInfo.js
+[getmodel]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/getModel.js
+[listmodels]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/listModels.js
+[apiref]: https://docs.microsoft.com/javascript/api/@azure/ai-form-recognizer
+[freesub]: https://azure.microsoft.com/free/
+[createinstance_azurecognitiveservicesaccount]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account
+[package]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/formrecognizer/ai-form-recognizer/README.md

sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeBusinessCard.js

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * This sample shows how to extract elements of a business card from a URL to a file using the prebuilt business card
+ * model.
+ *
+ * The prebuilt business card model can return several fields. For a detailed list of the fields supported by the
+ * business card model, see the `BusinessCard` type in the documentation, or refer to the following link:
+ *
+ * https://aka.ms/azsdk/formrecognizer/businesscardfieldschema
+ *
+ * @summary extract data from a business card document
+ */
+
+const {
+  AzureKeyCredential,
+  DocumentAnalysisClient,
+  PrebuiltModels
+} = require("@azure/ai-form-recognizer");
+
+const dotenv = require("dotenv");
+dotenv.config();
+
+async function main() {
+  const endpoint = process.env.FORM_RECOGNIZER_ENDPOINT ?? "<endpoint>";
+  const credential = new AzureKeyCredential(process.env.FORM_RECOGNIZER_API_KEY ?? "<api key>");
+
+  const client = new DocumentAnalysisClient(endpoint, credential);
+
+  const poller = await client.beginAnalyzeDocuments(
+    PrebuiltModels.BusinessCard,
+    // The form recognizer service will access the following URL to a business card image and extract data from it
+    "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/businessCard/business-card-english.jpg"
+  );
+
+  const {
+    documents: [result]
+  } = await poller.pollUntilDone();
+
+  // Use of PrebuiltModels.Receipt above (rather than the raw model ID), adds strong typing of the model's output
+  if (result) {
+    const businessCard = result.fields;
+    console.log("=== Business Card Information ===");
+
+    // There are more fields than just these few, and the model allows for multiple contact & company names as well as
+    // phone numbers, though we'll only show the first extracted values here.
+    const [name] = businessCard.contactNames?.values ?? [];
+    console.log("Name:", name?.properties.firstName?.value, name?.properties.lastName?.value);
+
+    const [company] = businessCard.companyNames?.values ?? [];
+    console.log("Company:", company?.value);
+
+    const [address] = businessCard.addresses?.values ?? [];
+    console.log("Address:", address?.value);
+  } else {
+    throw new Error("Expected at least one business card in the result.");
+  }
+}
+
+main().catch((error) => {
+  console.error("An error occurred:", error);
+  process.exit(1);
+});

sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeDocumentByModelId.js

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * This sample shows how to analyze a document using a model with a given ID. The model ID may refer to any model,
+ * whether custom, prebuilt, composed, etc.
+ *
+ * @summary analyze a document using a model by ID
+ */
+
+const { AzureKeyCredential, DocumentAnalysisClient } = require("@azure/ai-form-recognizer");
+
+const dotenv = require("dotenv");
+dotenv.config();
+
+async function main() {
+  const endpoint = process.env.FORM_RECOGNIZER_ENDPOINT ?? "<endpoint>";
+  const credential = new AzureKeyCredential(process.env.FORM_RECOGNIZER_API_KEY ?? "<api key>");
+  const client = new DocumentAnalysisClient(endpoint, credential);
+
+  const modelId = process.env.FORM_RECOGNIZER_CUSTOM_MODEL_ID ?? "<custom model ID>";
+
+  const poller = await client.beginAnalyzeDocuments(
+    modelId,
+    "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/receipt/contoso-receipt.png"
+  );
+
+  const {
+    documents: [document]
+  } = await poller.pollUntilDone();
+
+  if (!document) {
+    throw new Error("Expected at least one document in the result.");
+  }
+
+  console.log(
+    "Extracted document:",
+    document.docType,
+    `(confidence: ${document.confidence ?? "<undefined>"})`
+  );
+  console.log("Fields:", document.fields);
+}
+
+main().catch((error) => {
+  console.error("An error occurred:", error);
+  process.exit(1);
+});

sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeIdentityDocument.js

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * This sample shows how to extract elements of an identity document (such as a driver license or passport) from a URL
+ * to a file using the prebuilt identity document model.
+ *
+ * The prebuilt identity document model can return several fields. For a detailed list of the fields supported by the
+ * identity document model, see the `IdentityDocument` type in the documentation, or refer to the following link:
+ *
+ * https://aka.ms/azsdk/formrecognizer/iddocumentfieldschema
+ *
+ * @summary extract data from an identity document
+ */
+
+const {
+  AzureKeyCredential,
+  DocumentAnalysisClient,
+  PrebuiltModels
+} = require("@azure/ai-form-recognizer");
+
+const dotenv = require("dotenv");
+dotenv.config();
+
+async function main() {
+  const endpoint = process.env.FORM_RECOGNIZER_ENDPOINT ?? "<endpoint>";
+  const credential = new AzureKeyCredential(process.env.FORM_RECOGNIZER_API_KEY ?? "<api key>");
+
+  const client = new DocumentAnalysisClient(endpoint, credential);
+
+  const poller = await client.beginAnalyzeDocuments(
+    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"
+  );
+
+  const {
+    documents: [result]
+  } = await poller.pollUntilDone();
+
+  // Use of PrebuiltModels.Receipt above (rather than the raw model ID), adds strong typing of the model's output
+  if (result) {
+    // The identity document model has multiple document types, so we need to know which document type was actually
+    // extracted.
+    if (result.docType === "prebuilt:idDocument:driverLicense") {
+      const driverLicense = result.fields;
+
+      // For the sake of the example, we'll only show a few of the fields that are produced.
+      console.log("Extracted a Driver License:");
+      console.log("  Name:", driverLicense.firstName?.value, driverLicense.lastName?.value);
+      console.log("  License No.:", driverLicense.documentNumber?.value);
+      console.log("  Date of Birth:", driverLicense.dateOfBirth?.value);
+      console.log("  Expiration:", driverLicense.documentNumber?.value);
+    } else if (result.docType === "prebuilt:idDocument:passport") {
+      const passport = result.fields;
+
+      // The passport document type extracts and parses the Passport's machine-readable zone
+      const fields = passport.machineReadableZone?.properties;
+      console.log("Extracted a Passport:");
+      console.log("  Name:", fields?.firstName?.value, fields?.lastName?.value);
+      console.log("  Date of Birth:", fields?.dateOfBirth?.value);
+      console.log("  Nationality:", fields?.nationality?.value);
+      console.log("  Passport No.:", fields?.documentNumber?.value);
+      console.log("  Issuer:", fields?.countryRegion?.value);
+      console.log("  Expiration Date:", fields?.dateOfExpiration?.value);
+    } else {
+      // The only reason this would happen is if the client library's schema for the prebuilt identity document model is
+      // out of date, and a new document type has been introduced.
+      console.error("Unknown document type in result:", result);
+    }
+  } else {
+    throw new Error("Expected at least one receipt in the result.");
+  }
+}
+
+main().catch((error) => {
+  console.error("An error occurred:", error);
+  process.exit(1);
+});

sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeInvoice.js

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * This sample shows how to extract elements of an invoice from a URL to a file using the prebuilt invoice model.
+ *
+ * The prebuilt invoice model can return several fields. For a detailed list of the fields supported by the invoice
+ * model, see the `Invoice` type in the documentation, or refer to the following link:
+ *
+ * https://aka.ms/azsdk/formrecognizer/invoicefieldschema
+ *
+ * @summary extract data from an invoice document
+ */
+
+const {
+  AzureKeyCredential,
+  DocumentAnalysisClient,
+  PrebuiltModels
+} = require("@azure/ai-form-recognizer");
+
+const dotenv = require("dotenv");
+dotenv.config();
+
+async function main() {
+  const endpoint = process.env.FORM_RECOGNIZER_ENDPOINT ?? "<endpoint>";
+  const credential = new AzureKeyCredential(process.env.FORM_RECOGNIZER_API_KEY ?? "<api key>");
+
+  const client = new DocumentAnalysisClient(endpoint, credential);
+
+  const poller = await client.beginAnalyzeDocuments(
+    PrebuiltModels.Invoice,
+    // The form recognizer service will access the following URL to an invoice image and extract data from it
+    "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/invoice/sample_invoice.jpg"
+  );
+
+  const {
+    documents: [result]
+  } = await poller.pollUntilDone();
+
+  // Use of PrebuiltModels.Receipt above (rather than the raw model ID), adds strong typing of the model's output
+  if (result) {
+    const invoice = result.fields;
+
+    // The invoice model has many fields, and we will only show some of them for the sake of the example
+    console.log("Vendor Name:", invoice.vendorName?.value);
+    console.log("Customer Name:", invoice.customerName?.value);
+    console.log("Invoice Date:", invoice.invoiceDate?.value);
+    console.log("Due Date:", invoice.dueDate?.value);
+
+    console.log("Items:");
+    for (const { properties: item } of invoice.items?.values ?? []) {
+      console.log("-", item.productCode?.value ?? "<no product code>");
+      console.log("  Description:", item.description?.value);
+      console.log("  Quantity:", item.quantity?.value);
+      console.log("  Date:", item.date?.value);
+      console.log("  Unit:", item.unit?.value);
+      console.log("  Unit Price:", item.unitPrice?.value);
+      console.log("  Tax:", item.tax?.value);
+      console.log("  Amount:", item.amount?.value);
+    }
+
+    console.log("Subtotal:", invoice.subTotal?.value);
+    console.log("Previous Unpaid Balance:", invoice.previousUnpaidBalance?.value);
+    console.log("Tax:", invoice.totalTax?.value);
+    console.log("Amount Due:", invoice.amountDue?.value);
+  } else {
+    throw new Error("Expected at least one receipt in the result.");
+  }
+}
+
+main().catch((error) => {
+  console.error("An error occurred:", error);
+  process.exit(1);
+});