[Form Recognizer] Consistency changes (Azure#23069)

* update API

* changelog

* upodate readme

* test fixes

Author: HarshaNalluru

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

@@ -8,7 +8,7 @@
 
 ### Breaking Changes
 
-- Renamed the `getModel` and `listModels` methods of `DocumentModelAdministrationClient` to `getDocumentModel` and `listDocumentModels` respectively.
+- Renamed `DocumentModelAdministrationClient` methods to have the word `Document` in them, for example `getModel` and `listModels` are updated to `getDocumentModel` and `listDocumentModels` respectively.
 
 ## 4.0.0-beta.6 (2022-08-09)
 

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

@@ -143,11 +143,11 @@ const client = new DocumentAnalysisClient("<endpoint>", new DefaultAzureCredenti
 
 `DocumentModelAdministrationClient` provides operations for managing (creating, reading, listing, and deleting) models in the Form Recognizer resource:
 
-- `beginBuildModel` starts an operation to create a new document model from your own training data set. The created model can extract fields according to a custom schema. The training data are expected to be located in an Azure Storage container and organized according to a particular convention. See the [service's documentation on creating a training data set][fr-build-training-set] for a more detailed explanation of applying labels to a training data set.
-- `beginComposeModel` starts an operation to compose multiple models into a single model. When used for custom form recognition, the new composed model will first perform a classification of the input documents to determine which of its submodels is most appropriate.
+- `beginBuildDocumentModel` starts an operation to create a new document model from your own training data set. The created model can extract fields according to a custom schema. The training data are expected to be located in an Azure Storage container and organized according to a particular convention. See the [service's documentation on creating a training data set][fr-build-training-set] for a more detailed explanation of applying labels to a training data set.
+- `beginComposeDocumentModel` starts an operation to compose multiple models into a single model. When used for custom form recognition, the new composed model will first perform a classification of the input documents to determine which of its submodels is most appropriate.
 - `beginCopyModelTo` starts an operation to copy a custom model from one Form Recognizer resource to another (or even to the same Form Recognizer resource). It requires a `CopyAuthorization` from the target Form Recognizer resource, which can be generated using the `getCopyAuthorization` method.
 - `getResourceDetails` retrieves information about the Form Recognizer resource's limits, such as the number of custom models and the maximum number of models the resource can support.
-- `getModel`, `listModels`, and `deleteModel` enable managing models in the resource.
+- `getDocumentModel`, `listDocumentModels`, and `deleteDocumentModel` enable managing models in the resource.
 - `getOperation` and `listOperations` enable viewing the status of model creation operations, even those operations that are ongoing or that have failed. Operations are retained for 24 hours.
 
 Please note that models can also be created using the Form Recognizer service's graphical user interface: [Form Recognizer Studio (Preview)][fr-studio].
@@ -320,7 +320,7 @@ Each of the above prebuilt models produces `documents` (extracted instances of t
 
 For information about the fields of all of these models, see [the service's documentation of the available prebuilt models](https://aka.ms/azsdk/formrecognizer/models).
 
-The fields of all prebuilt models may also be accessed programmatically using the `getModel` method (by their model IDs) of `DocumentModelAdministrationClient` and inspecting the `docTypes` field in the result.
+The fields of all prebuilt models may also be accessed programmatically using the `getDocumentModel` method (by their model IDs) of `DocumentModelAdministrationClient` and inspecting the `docTypes` field in the result.
 
 ### Use the "layout" prebuilt
 
@@ -518,7 +518,7 @@ async function main() {
   // The second parameter is the SAS-encoded URL to an Azure Storage container with the training documents.
   // The third parameter is the build mode: one of "template" (the only mode prior to 4.0.0-beta.3) or "neural".
   // See https://aka.ms/azsdk/formrecognizer/buildmode for more information about build modes.
-  const poller = await client.beginBuildModel("<model ID>", containerSasUrl, "template", {
+  const poller = await client.beginBuildDocumentModel("<model ID>", containerSasUrl, "template", {
     // The model description is optional and can be any text.
     description: "This is my new model!",
     onProgress: ({ status }) => {
@@ -571,34 +571,34 @@ async function main() {
   const apiKey = "<api key>";
   const client = new DocumentModelAdministrationClient(endpoint, new AzureKeyCredential(apiKey));
 
-  // Produces an async iterable that supports paging (`PagedAsyncIterableIterator`). The `listModels` method will only
+  // Produces an async iterable that supports paging (`PagedAsyncIterableIterator`). The `listDocumentModels` method will only
   // iterate over model summaries, which do not include detailed schema information. Schema information is only returned
-  // from `getModel` as part of the full model information.
-  const models = client.listModels();
+  // from `getDocumentModel` as part of the full model information.
+  const models = client.listDocumentModels();
   let i = 1;
   for await (const summary of models) {
     console.log(`Model ${i++}:`, summary);
   }
 
   // The iterable is paged, and the application can control the flow of paging if needed
   i = 1;
-  for await (const page of client.listModels().byPage()) {
+  for await (const page of client.listDocumentModels().byPage()) {
     for (const summary of page) {
       console.log(`Model ${i++}`, summary);
     }
   }
 
   // We can also get a full ModelInfo by ID. Here we only show the basic information. See the documentation and the
-  // `getModel` sample program for information about the `docTypes` field, which contains the model's document type
+  // `getDocumentModel` sample program for information about the `docTypes` field, which contains the model's document type
   // schemas.
-  const model = await client.getModel("<model ID>");
+  const model = await client.getDocumentModel("<model ID>");
   console.log("ID", model.modelId);
   console.log("Created:", model.createdDateTime);
   console.log("Description: ", model.description ?? "<none>");
 
   // A model can also be deleted by its model ID. Once it is deleted, it CANNOT be recovered.
   const modelIdToDelete = "<model ID that should be deleted forever>";
-  await client.deleteModel(modelIdToDelete);
+  await client.deleteDocumentModel(modelIdToDelete);
 }
 
 main().catch((err) => {

sdk/formrecognizer/ai-form-recognizer/review/ai-form-recognizer.api.md

@@ -71,11 +71,11 @@ export type AnalyzeResultOperationStatus = "notStarted" | "running" | "failed" |
 export { AzureKeyCredential }
 
 // @public
-export interface BeginBuildModelOptions extends CreateModelOptions {
+export interface BeginBuildDocumentModelOptions extends CreateDocumentModelOptions {
 }
 
 // @public
-export interface BeginComposeModelOptions extends CreateModelOptions {
+export interface BeginComposeDocumentModelOptions extends CreateDocumentModelOptions {
 }
 
 // @public
@@ -104,11 +104,11 @@ export interface CopyAuthorization {
 }
 
 // @public
-export function createModelFromSchema(schema: Omit<DocumentModelDetails, "createdDateTime">): DocumentModel<AnalyzeResult<unknown>>;
+export interface CreateDocumentModelOptions extends OperationOptions, CommonModelCreationOptions, PollerOptions<DocumentModelOperationState> {
+}
 
 // @public
-export interface CreateModelOptions extends OperationOptions, CommonModelCreationOptions, PollerOptions<DocumentModelOperationState> {
-}
+export function createModelFromSchema(schema: Omit<DocumentModelDetails, "createdDateTime">): DocumentModel<AnalyzeResult<unknown>>;
 
 // @public
 export interface CurrencyValue {
@@ -123,7 +123,7 @@ export interface CustomDocumentModelsDetails {
 }
 
 // @public
-export interface DeleteModelOptions extends OperationOptions {
+export interface DeleteDocumentModelOptions extends OperationOptions {
 }
 
 // @public
@@ -267,10 +267,10 @@ export class DocumentModelAdministrationClient {
     constructor(endpoint: string, credential: TokenCredential, options?: DocumentModelAdministrationClientOptions);
     constructor(endpoint: string, credential: KeyCredential, options?: DocumentModelAdministrationClientOptions);
     constructor(endpoint: string, credential: KeyCredential | TokenCredential, options?: DocumentModelAdministrationClientOptions);
-    beginBuildModel(modelId: string, containerUrl: string, buildMode: DocumentModelBuildMode, options?: BeginBuildModelOptions): Promise<DocumentModelPoller>;
-    beginComposeModel(modelId: string, componentModelIds: Iterable<string>, options?: BeginComposeModelOptions): Promise<DocumentModelPoller>;
+    beginBuildDocumentModel(modelId: string, containerUrl: string, buildMode: DocumentModelBuildMode, options?: BeginBuildDocumentModelOptions): Promise<DocumentModelPoller>;
+    beginComposeDocumentModel(modelId: string, componentModelIds: Iterable<string>, options?: BeginComposeDocumentModelOptions): Promise<DocumentModelPoller>;
     beginCopyModelTo(sourceModelId: string, authorization: CopyAuthorization, options?: BeginCopyModelOptions): Promise<DocumentModelPoller>;
-    deleteModel(modelId: string, options?: DeleteModelOptions): Promise<void>;
+    deleteDocumentModel(modelId: string, options?: DeleteDocumentModelOptions): Promise<void>;
     getCopyAuthorization(destinationModelId: string, options?: GetCopyAuthorizationOptions): Promise<CopyAuthorization>;
     getDocumentModel(modelId: string, options?: GetModelOptions): Promise<DocumentModelDetails>;
     getOperation(operationId: string, options?: GetOperationOptions): Promise<OperationDetails>;

sdk/formrecognizer/ai-form-recognizer/samples-dev/buildModel.ts

@@ -34,7 +34,7 @@ async function main() {
 
   const client = new DocumentModelAdministrationClient(endpoint, credential);
 
-  const poller = await client.beginBuildModel(
+  const poller = await client.beginBuildDocumentModel(
     modelId,
     trainingDataSasUrl,
     DocumentModelBuildMode.Template

sdk/formrecognizer/ai-form-recognizer/samples-dev/composeModel.ts

@@ -54,7 +54,7 @@ export async function main() {
     Object.entries(purchaseOrderSasUrls)
       .map(async ([kind, sasUrl]) => {
         const modelId = kind + "ComponentModel" + random.substring(random.length - 6);
-        const poller = await client.beginBuildModel(
+        const poller = await client.beginBuildDocumentModel(
           modelId,
           sasUrl,
           DocumentModelBuildMode.Neural,
@@ -74,7 +74,7 @@ export async function main() {
   // Finally, create the composed model.
 
   const composedModelId = "purchaseOrders" + random.substring(random.length - 6);
-  const poller = await client.beginComposeModel(composedModelId, modelIds, {
+  const poller = await client.beginComposeDocumentModel(composedModelId, modelIds, {
     description:
       "A composed model that classifies purchase order documents and extracts data from them.",
     onProgress(state) {

sdk/formrecognizer/ai-form-recognizer/src/documentModelAdministrationClient.ts

@@ -26,7 +26,7 @@ import {
 import { lro } from "./lro/util/poller";
 import {
   BeginCopyModelOptions,
-  DeleteModelOptions,
+  DeleteDocumentModelOptions,
   DocumentModelAdministrationClientOptions,
   GetCopyAuthorizationOptions,
   GetResourceDetailsOptions,
@@ -36,8 +36,8 @@ import {
   ListOperationsOptions,
 } from "./options";
 import {
-  BeginBuildModelOptions,
-  BeginComposeModelOptions,
+  BeginBuildDocumentModelOptions,
+  BeginComposeDocumentModelOptions,
   DocumentModelBuildMode,
 } from "./options/BuildModelOptions";
 import { Mappers, SERIALIZER, makeServiceClient } from "./util";
@@ -168,7 +168,7 @@ export class DocumentModelAdministrationClient {
    * const modelId = "aNewModel";
    * const containerUrl = "<training data container SAS URL>";
    *
-   * const poller = await client.beginBuildModel(modelId, containerUrl, {
+   * const poller = await client.beginBuildDocumentModel(modelId, containerUrl, {
    *   // Optionally, a text description may be attached to the model
    *   description: "This is an example model!"
    * });
@@ -191,14 +191,14 @@ export class DocumentModelAdministrationClient {
    * @param options - optional settings for the model build operation
    * @returns a long-running operation (poller) that will eventually produce the created model information or an error
    */
-  public async beginBuildModel(
+  public async beginBuildDocumentModel(
     modelId: string,
     containerUrl: string,
     buildMode: DocumentModelBuildMode,
-    options: BeginBuildModelOptions = {}
+    options: BeginBuildDocumentModelOptions = {}
   ): Promise<DocumentModelPoller> {
     return this._tracing.withSpan(
-      "DocumentModelAdministrationClient.beginBuildModel",
+      "DocumentModelAdministrationClient.beginBuildDocumentModel",
       options,
       (finalOptions) =>
         this.createDocumentModelPoller({
@@ -237,7 +237,7 @@ export class DocumentModelAdministrationClient {
    *
    * // The resulting composed model can classify and extract data from documents
    * // conforming to any of the above document types
-   * const poller = await client.beginComposeModel(modelId, subModelIds, {
+   * const poller = await client.beginComposeDocumentModel(modelId, subModelIds, {
    *   description: "This is a composed model that can handle several document types."
    * });
    *
@@ -258,13 +258,13 @@ export class DocumentModelAdministrationClient {
    * @param options - optional settings for model creation
    * @returns a long-running operation (poller) that will eventually produce the created model information or an error
    */
-  public async beginComposeModel(
+  public async beginComposeDocumentModel(
     modelId: string,
     componentModelIds: Iterable<string>,
-    options: BeginComposeModelOptions = {}
+    options: BeginComposeDocumentModelOptions = {}
   ): Promise<DocumentModelPoller> {
     return this._tracing.withSpan(
-      "DocumentModelAdministrationClient.beginComposeModel",
+      "DocumentModelAdministrationClient.beginComposeDocumentModel",
       options,
       (finalOptions) =>
         this.createDocumentModelPoller({
@@ -701,7 +701,10 @@ export class DocumentModelAdministrationClient {
    * @param modelId - the unique ID of the model to delete from the resource
    * @param options - optional settings for the request
    */
-  public deleteModel(modelId: string, options: DeleteModelOptions = {}): Promise<void> {
+  public deleteDocumentModel(
+    modelId: string,
+    options: DeleteDocumentModelOptions = {}
+  ): Promise<void> {
     return this._tracing.withSpan(
       "DocumentModelAdministrationClient.deleteDocumentModel",
       options,

sdk/formrecognizer/ai-form-recognizer/src/options/BuildModelOptions.ts

@@ -56,17 +56,17 @@ export interface CommonModelCreationOptions {
 /**
  * Options for the model creation operation.
  */
-export interface CreateModelOptions
+export interface CreateDocumentModelOptions
   extends OperationOptions,
     CommonModelCreationOptions,
     PollerOptions<DocumentModelOperationState> {}
 
 /**
  * Options for the model build operation.
  */
-export interface BeginBuildModelOptions extends CreateModelOptions {}
+export interface BeginBuildDocumentModelOptions extends CreateDocumentModelOptions {}
 
 /**
  * Options for the model compose operation.
  */
-export interface BeginComposeModelOptions extends CreateModelOptions {}
+export interface BeginComposeDocumentModelOptions extends CreateDocumentModelOptions {}

sdk/formrecognizer/ai-form-recognizer/src/options/DeleteModelOptions.ts

@@ -6,4 +6,4 @@ import { OperationOptions } from "@azure/core-client";
 /**
  * Options for model deletion.
  */
-export interface DeleteModelOptions extends OperationOptions {}
+export interface DeleteDocumentModelOptions extends OperationOptions {}

sdk/formrecognizer/ai-form-recognizer/src/options/index.ts

@@ -3,14 +3,14 @@
 
 import { AnalyzeDocumentOptions } from "./AnalyzeDocumentsOptions";
 import {
-  CreateModelOptions,
+  CreateDocumentModelOptions,
   CommonModelCreationOptions,
   DocumentModelBuildMode,
-  BeginBuildModelOptions,
-  BeginComposeModelOptions,
+  BeginBuildDocumentModelOptions,
+  BeginComposeDocumentModelOptions,
 } from "./BuildModelOptions";
 import { BeginCopyModelOptions } from "./BeginCopyModelOptions";
-import { DeleteModelOptions } from "./DeleteModelOptions";
+import { DeleteDocumentModelOptions } from "./DeleteModelOptions";
 import {
   DocumentAnalysisClientOptions,
   DocumentModelAdministrationClientOptions,
@@ -28,9 +28,9 @@ import { PollerOptions } from "./PollerOptions";
 
 export {
   AnalyzeDocumentOptions,
-  CreateModelOptions,
-  BeginBuildModelOptions,
-  BeginComposeModelOptions,
+  CreateDocumentModelOptions,
+  BeginBuildDocumentModelOptions,
+  BeginComposeDocumentModelOptions,
   CommonModelCreationOptions,
   BeginCopyModelOptions,
   DocumentModelBuildMode,
@@ -41,7 +41,7 @@ export {
   GetResourceDetailsOptions,
   GetModelOptions,
   GetOperationOptions,
-  DeleteModelOptions,
+  DeleteDocumentModelOptions,
   ListModelsOptions,
   ListOperationsOptions,
   PollerOptions,

sdk/formrecognizer/ai-form-recognizer/test/private/tracing.spec.ts

@@ -106,25 +106,25 @@ describe("supports tracing", function () {
     it("deleteModel", () =>
       assert.supportsTracing(
         fakeIt(async (options: { tracingOptions?: OperationTracingOptions }) => {
-          await dmac.deleteModel("test", options);
+          await dmac.deleteDocumentModel("test", options);
         }),
         ["DocumentModelAdministrationClient.deleteDocumentModel"]
       ));
 
     it("beginBuildModel", () =>
       assert.supportsTracing(
         fakeIt(async (options: { tracingOptions?: OperationTracingOptions }) => {
-          await (await dmac.beginBuildModel("test", "test", "neural", options)).poll();
+          await (await dmac.beginBuildDocumentModel("test", "test", "neural", options)).poll();
         }),
-        ["DocumentModelAdministrationClient.beginBuildModel"]
+        ["DocumentModelAdministrationClient.beginBuildDocumentModel"]
       ));
 
     it("beginComposeModel", () =>
       assert.supportsTracing(
         fakeIt(async (options: { tracingOptions?: OperationTracingOptions }) => {
-          await dmac.beginComposeModel("test", [], options);
+          await dmac.beginComposeDocumentModel("test", [], options);
         }),
-        ["DocumentModelAdministrationClient.beginComposeModel"]
+        ["DocumentModelAdministrationClient.beginComposeDocumentModel"]
       ));
 
     it("getCopyAuthorization", () =>