[ai-form-recognizer] Final docs changes pre-GA (Azure#10714)

* [ai-form-recognizer] Document URL encoding requirement. * Reordered README examples sections and added some clearer introductions. * Added snippet pointer and capitalized headers * Better documentation for finding resource id and region. * Quick fix to samples in README * Addressing feedback
AzureSDKAutomation · Aug 20, 2020 · b2e1d53 · b2e1d53
1 parent 4a4bd52
commit b2e1d53
Show file tree

Hide file tree

Showing 3 changed files with 114 additions and 98 deletions.
diff --git a/sdk/formrecognizer/ai-form-recognizer/README.md b/sdk/formrecognizer/ai-form-recognizer/README.md
@@ -125,6 +125,8 @@ const client = new FormRecognizerClient("<endpoint>", new DefaultAzureCredential
 
 Please note that models can also be trained using a graphical user interface such as the [Form Recognizer Labeling Tool][fr-labeling-tool].
 
+Sample code snippets that illustrate the use of `FormTrainingClient` can be found [below](#train-a-model).
+
 ### Long-Running Operations
 Long-running operations are operations which consist of an initial request sent to the service to start an operation,followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has succeeded, to get the result.
 
@@ -134,67 +136,57 @@ to illustrate using long-running operations [below](#examples).
 ## Examples
 The following section provides several JavaScript code snippets illustrating common patterns used in the Form Recognizer client libraries.
 
-* [Recognize receipts](#recognize-receipts)
-* [Recognize content](#recognize-content)
-* [Train model](#train-model)
-* [Recognize forms using a custom model](#recognize-forms-using-a-custom-model)
-* [Listing all models](#listing-all-models)
+* [Recognize Forms Using a Custom Model](#recognize-forms-using-a-custom-model)
+* [Recognize Content](#recognize-content)
+* [Recognize Receipts](#recognize-receipts)
+* [Train a Model](#train-a-model)
+* [Listing All Models](#listing-all-models)
 
-### Recognize receipts
+### Recognize Forms Using a Custom Model
 
-Recognize data from sales receipts using the pre-built model.
+Recognize name/value pairs and table data from forms. These models are trained with your own data, so they're tailored to your forms. A custom model should only be used with forms of the same document structure as those used to train the model.
 
 ```javascript
 const { FormRecognizerClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");
+
 const fs = require("fs");
 
 async function main() {
   const endpoint = "<cognitive services endpoint>";
   const apiKey = "<api key>";
-  const path = "<path to your receipt document>"; // pdf/jpeg/png/tiff formats
+  const modelId = "<model id>";
+  const path = "<path to a form document>";
 
   const readStream = fs.createReadStream(path);
 
   const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));
-  const poller = await client.beginRecognizeReceipts(readStream, "image/jpeg", {
+  const poller = await client.beginRecognizeCustomForms(modelId, readStream, "application/pdf", {
     onProgress: (state) => { console.log(`status: ${state.status}`); }
   });
+  const forms = await poller.pollUntilDone();
 
-  const receipts = await poller.pollUntilDone();
-
-  if (!receipts || receipts.length <= 0) {
-    throw new Error("Expecting at lease one receipt in analysis result");
-  }
-
-  const receipt = receipts[0];
-  console.log("First receipt:");
-  // For a list of fields that are contained in the response, please refer to the "Supported fields" section at the following link: https://aka.ms/azsdk/formrecognizer/receiptfields
-  const receiptTypeField = receipt.fields["ReceiptType"];
-  if (receiptTypeField.valueType === "string") {
-    console.log(`  Receipt Type: '${receiptTypeField.value || "<missing>"}', with confidence of ${receiptTypeField.confidence}`);
-  }
-  const merchantNameField = receipt.fields["MerchantName"];
-  if (merchantNameField.valueType === "string") {
-    console.log(`  Merchant Name: '${merchantNameField.value || "<missing>"}', with confidence of ${merchantNameField.confidence}`);
-  }
-  const transactionDate = receipt.fields["TransactionDate"];
-  if (transactionDate.valueType === "date") {
-    console.log(`  Transaction Date: '${transactionDate.value || "<missing>"}', with confidence of ${transactionDate.confidence}`);
-  }
-  const itemsField = receipt.fields["Items"];
-  if (itemsField.valueType === "array") {
-    for (const itemField of itemsField.value || []) {
-      if (itemField.valueType === "object") {
-        const itemNameField = itemField.value["Name"];
-        if (itemNameField.valueType === "string") {
-          console.log(`    Item Name: '${itemNameField.value || "<missing>"}', with confidence of ${itemNameField.confidence}`);
+  console.log("Forms:");
+  for (const form of forms || []) {
+    console.log(`${form.formType}, page range: ${form.pageRange}`);
+    console.log("Pages:");
+    for (const page of form.pages || []) {
+      console.log(`Page number: ${page.pageNumber}`);
+      console.log("Tables");
+      for (const table of page.tables || []) {
+        for (const cell of table.cells) {
+          console.log(`cell (${cell.rowIndex},${cell.columnIndex}) ${cell.text}`);
         }
       }
     }
-  }
-  const totalField = receipt.fields["Total"];
-  if (totalField.valueType === "number") {
-    console.log(`  Total: '${totalField.value || "<missing>"}', with confidence of ${totalField.confidence}`);
+
+    console.log("Fields:");
+    for (const fieldName in form.fields) {
+      // each field is of type FormField
+      const field = form.fields[fieldName];
+      console.log(
+        `Field ${fieldName} has value '${field.value}' with a confidence score of ${field.confidence}`
+      );
+    }
   }
 }
 
@@ -203,12 +195,16 @@ main().catch((err) => {
 });
 ```
 
-### Recognize content
+Alternatively, a form URL can be used to recognize custom forms using the `beginRecognizeCustomFormsFromUrl` method. Methods
+with a `FromUrl` suffix that use URLs instead of streams exist for all of the recognition methods.
+
+### Recognize Content
 
 Recognize text and table structures, along with their bounding box, from documents
 
 ```javascript
 const { FormRecognizerClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");
+
 const fs = require("fs");
 
 async function main() {
@@ -243,7 +239,70 @@ main().catch((err) => {
 });
 ```
 
-### Train model
+### Recognize Receipts
+
+Recognize data from USA sales receipts using the pre-built model. A list of receipt fields recognized by the service can be found [here](https://aka.ms/azsdk/formrecognizer/receiptfields).
+
+```javascript
+const { FormRecognizerClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");
+
+const fs = require("fs");
+
+async function main() {
+  const endpoint = "<cognitive services endpoint>";
+  const apiKey = "<api key>";
+  const path = "<path to your receipt document>"; // pdf/jpeg/png/tiff formats
+
+  const readStream = fs.createReadStream(path);
+
+  const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));
+  const poller = await client.beginRecognizeReceipts(readStream, "image/jpeg", {
+    onProgress: (state) => { console.log(`status: ${state.status}`); }
+  });
+
+  const receipts = await poller.pollUntilDone();
+
+  if (!receipts || receipts.length <= 0) {
+    throw new Error("Expecting at lease one receipt in analysis result");
+  }
+
+  const receipt = receipts[0];
+  console.log("First receipt:");
+  const receiptTypeField = receipt.fields["ReceiptType"];
+  if (receiptTypeField.valueType === "string") {
+    console.log(`  Receipt Type: '${receiptTypeField.value || "<missing>"}', with confidence of ${receiptTypeField.confidence}`);
+  }
+  const merchantNameField = receipt.fields["MerchantName"];
+  if (merchantNameField.valueType === "string") {
+    console.log(`  Merchant Name: '${merchantNameField.value || "<missing>"}', with confidence of ${merchantNameField.confidence}`);
+  }
+  const transactionDate = receipt.fields["TransactionDate"];
+  if (transactionDate.valueType === "date") {
+    console.log(`  Transaction Date: '${transactionDate.value || "<missing>"}', with confidence of ${transactionDate.confidence}`);
+  }
+  const itemsField = receipt.fields["Items"];
+  if (itemsField.valueType === "array") {
+    for (const itemField of itemsField.value || []) {
+      if (itemField.valueType === "object") {
+        const itemNameField = itemField.value["Name"];
+        if (itemNameField.valueType === "string") {
+          console.log(`    Item Name: '${itemNameField.value || "<missing>"}', with confidence of ${itemNameField.confidence}`);
+        }
+      }
+    }
+  }
+  const totalField = receipt.fields["Total"];
+  if (totalField.valueType === "number") {
+    console.log(`  Total: '${totalField.value || "<missing>"}', with confidence of ${totalField.confidence}`);
+  }
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});
+```
+
+### Train a Model
 
 Train a machine-learned model on your own form type. The resulting model will be able to recognize values from the types of forms it was trained on. Provide a container SAS url to your Azure Storage Blob container where you're storing the training documents. See details on setting this up in the [service quickstart documentation][quickstart_training]. This sample creates and trains a custom model without using labels.
 
@@ -299,56 +358,7 @@ main().catch((err) => {
 
 For information on creating a labeled training data set, see the documentation for the [using the sample labeling tool][quickstart_labeling] and the [labeled model training sample][labeled_sample].
 
-### Recognize forms using a custom model
-
-```javascript
-const { FormRecognizerClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");
-
-async function main() {
-  const endpoint = "<cognitive services endpoint>";
-  const apiKey = "<api key>";
-  const modelId = "<model id>";
-  const path = "<path to a form document>";
-
-  const readStream = fs.createReadStream(path);
-
-  const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));
-  const poller = await client.beginRecognizeCustomForms(modelId, readStream, "application/pdf", {
-    onProgress: (state) => { console.log(`status: ${state.status}`); }
-  });
-  const forms = await poller.pollUntilDone();
-
-  console.log("Forms:");
-  for (const form of forms || []) {
-    console.log(`${form.formType}, page range: ${form.pageRange}`);
-    console.log("Pages:");
-    for (const page of form.pages || []) {
-      console.log(`Page number: ${page.pageNumber}`);
-      console.log("Tables");
-      for (const table of page.tables || []) {
-        for (const cell of table.cells) {
-          console.log(`cell (${cell.rowIndex},${cell.columnIndex}) ${cell.text}`);
-        }
-      }
-    }
-
-    console.log("Fields:");
-    for (const fieldName in form.fields) {
-      // each field is of type FormField
-      const field = form.fields[fieldName];
-      console.log(
-        `Field ${fieldName} has value '${field.value}' with a confidence score of ${field.confidence}`
-      );
-    }
-  }
-}
-
-main().catch((err) => {
-  console.error("The sample encountered an error:", err);
-});
-```
-
-### Listing all models
+### Listing All Models
 
 Listing custom models in the current cognitive service account. This sample shows several ways to iterate through the result.
 

diff --git a/sdk/formrecognizer/ai-form-recognizer/src/formRecognizerClient.ts b/sdk/formrecognizer/ai-form-recognizer/src/formRecognizerClient.ts
@@ -300,7 +300,7 @@ export class FormRecognizerClient {
    * const pages = await poller.pollUntilDone();
    * ```
    * @summary Recognizes content/layout information from a url to a form document
-   * @param {string} formUrl Url to an accessible form document. Supported document types include PDF, JPEG, PNG, and TIFF.
+   * @param {string} formUrl Url to a form document that is accessible from the service. Must be a valid, encoded URL to one of the following supported document types: PDF, JPEG, PNG, and TIFF.
    * @param {BeginRecognizeContentOptions} [options] Options to start content recognition operation
    */
   public async beginRecognizeContentFromUrl(
@@ -428,7 +428,7 @@ export class FormRecognizerClient {
    * ```
    * @summary Recognizes form information from a url to a form document using a custom form model.
    * @param {string} modelId Id of the custom form model to use
-   * @param {string} formUrl Url to an accessible form document. Supported document types include PDF, JPEG, PNG, and TIFF.
+   * @param {string} formUrl Url to a form document that is accessible from the service. Must be a valid, encoded URL to one of the following supported document types: PDF, JPEG, PNG, and TIFF.
    * @param {BeginRecognizeFormsOptions} [options] Options to start the form recognition operation
    */
   public async beginRecognizeCustomFormsFromUrl(
@@ -635,7 +635,7 @@ export class FormRecognizerClient {
    * }
    * ```
    * @summary Recognizes receipt information from a given accessible url to input document
-   * @param {string} receiptUrl Url to an accesssible receipt document. Supported document types include PDF, JPEG, PNG, and TIFF.
+   * @param {string} receiptUrl Url to a receipt document that is accessible from the service. Must be a valid, encoded URL to one of the following supported document types: PDF, JPEG, PNG, and TIFF.
    * @param {BeginRecognizeFormsOptions} [options] Options to start receipt recognition operation
    */
   public async beginRecognizeReceiptsFromUrl(

diff --git a/sdk/formrecognizer/ai-form-recognizer/src/formTrainingClient.ts b/sdk/formrecognizer/ai-form-recognizer/src/formTrainingClient.ts
@@ -515,10 +515,16 @@ export class FormTrainingClient {
   }
 
   /**
-   * Generates authorization for copying a custom model into this Azure Form Recognizer resource.
+   * Generate an authorization for copying a custom model into this Azure Form Recognizer resource.
+   *
+   * This method should be called on a client that is authenticated using the target resource (where the
+   * model will be copied to) credentials, and the output can be passed as the `target` parameter to the
+   * `beginCopyModel` method of a source client.
+   *
+   * The required `resourceId` and `resourceRegion` are properties of an Azure Form Recognizer resource and their values can be found in the Azure Portal.
    *
    * @param {string} resourceId Id of the Azure Form Recognizer resource where a custom model will be copied to
-   * @param {string} resourceRegion Location of the Azure Form Recognizer resource
+   * @param {string} resourceRegion Location of the Azure Form Recognizer resource, must be a valid region name supported by Azure Cognitive Services. See https://aka.ms/azsdk/cognitiveservices/regionalavailability for information about the regional availability of Azure Cognitive Services.
    * @param {GetCopyAuthorizationOptions} [options={}] Options to get copy authorization operation
    * @returns {Promise<CopyAuthorization>} The authorization to copy a custom model
    */