Class DocumentModelAdministrationClient

Build a new document classifier with the given classifier ID and document types.

The classifier ID must be unique among classifiers within the resource.

The document types are given as an object that maps the name of the document type to the training data set for that document type. Two training data input methods are supported:

• azureBlobSource, which trains a classifier using the data in the given Azure Blob Storage container.
• azureBlobFileListSource, which is similar to azureBlobSource but allows for more fine-grained control over the files that are included in the training data set by using a JSONL-formatted file list.

The Form Recognizer service reads the training data set from an Azure Storage container, given as a URL to the container with a SAS token that allows the service backend to communicate with the container. At a minimum, the "read" and "list" permissions are required. In addition, the data in the given container must be organized according to a particular convention, which is documented in the service's documentation for building custom document classifiers.

Example

const classifierId = "aNewClassifier";
const containerUrl1 = "<training data container SAS URL 1>";
const containerUrl2 = "<training data container SAS URL 2>";

const poller = await client.beginBuildDocumentClassifier(
  classifierId,
  {
    // The document types. Each entry in this object should map a document type name to a
    // `ClassifierDocumentTypeDetails` object
    "formX": {
      azureBlobSource: {
        containerUrl: containerUrl1,
      }
    },
    "formY": {
      azureBlobFileListSource: {
        containerUrl: containerUrl2,
        fileList: "path/to/fileList.jsonl"
      }
    },
  },
  {
    // Optionally, a text description may be attached to the classifier
    description: "This is an example classifier!"
  }
);

// Classifier building, like model creation operations, returns a poller that eventually produces a
// DocumentClassifierDetails object
const classifierDetails = await poller.pollUntilDone();

const {
  classifierId, // identical to the classifierId given when creating the classifier
  description, // identical to the description given when creating the classifier (if any)
  createdOn, // the Date (timestamp) that the classifier was created
  docTypes // information about the document types in the classifier and their details
} = classifierDetails;

Returns

a long-running operation (poller) that will eventually produce the created classifier details or an error

Build a new model with a given ID from a set of input documents and labeled fields.

The Model ID can consist of any text, so long as it does not begin with "prebuilt-" (as these models refer to prebuilt Form Recognizer models that are common to all resources), and so long as it does not already exist within the resource.

The Form Recognizer service reads the training data set from an Azure Storage container, given as a URL to the container with a SAS token that allows the service backend to communicate with the container. At a minimum, the "read" and "list" permissions are required. In addition, the data in the given container must be organized according to a particular convention, which is documented in the service's documentation for building custom models.

Example

const modelId = "aNewModel";
const containerUrl = "<training data container SAS URL>";

const poller = await client.beginBuildDocumentModel(modelId, containerUrl, {
  // Optionally, a text description may be attached to the model
  description: "This is an example model!"
});

// Model building, like all other model creation operations, returns a poller that eventually produces a ModelDetails
// object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the model
  description, // identical to the description given when creating the model
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types in the model and their field schemas
} = modelDetails;

Returns

a long-running operation (poller) that will eventually produce the created model information or an error

Build a new model with a given ID from a model content source.

The Model ID can consist of any text, so long as it does not begin with "prebuilt-" (as these models refer to prebuilt Form Recognizer models that are common to all resources), and so long as it does not already exist within the resource.

The content source describes the mechanism the service will use to read the input training data. See the DocumentModelContentSource type for more information.

Example

const modelId = "aNewModel";

const poller = await client.beginBuildDocumentModel(modelId, { containerUrl: "<SAS-encoded blob container URL>" }, {
  // Optionally, a text description may be attached to the model
  description: "This is an example model!"
});

// Model building, like all other model creation operations, returns a poller that eventually produces a ModelDetails
// object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the model
  description, // identical to the description given when creating the model
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types in the model and their field schemas
} = modelDetails;

Returns

a long-running operation (poller) that will eventually produce the created model information or an error

Creates a single composed model from several pre-existing submodels.

The resulting composed model combines the document types of its component models, and inserts a classification step into the extraction pipeline to determine which of its component submodels is most appropriate for the given input.

Example

const modelId = "aNewComposedModel";
const subModelIds = [
  "documentType1Model",
  "documentType2Model",
  "documentType3Model"
];

// The resulting composed model can classify and extract data from documents
// conforming to any of the above document types
const poller = await client.beginComposeDocumentModel(modelId, subModelIds, {
  description: "This is a composed model that can handle several document types."
});

// Model composition, like all other model creation operations, returns a poller that eventually produces a
// ModelDetails object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the model
  description, // identical to the description given when creating the model
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types of the composed submodels
} = modelDetails;

Returns

a long-running operation (poller) that will eventually produce the created model information or an error

Copies a model with the given ID into the resource and model ID encoded by a given copy authorization.

See CopyAuthorization and getCopyAuthorization.

Example

// We need a client for the source model's resource
const sourceEndpoint = "https://<source resource name>.cognitiveservices.azure.com";
const sourceCredential = new AzureKeyCredential("<source api key>");
const sourceClient = new DocumentModelAdministrationClient(sourceEndpoint, sourceCredential);

// We create the copy authorization using a client authenticated with the destination resource. Note that these two
// resources can be the same (you can copy a model to a new ID in the same resource).
const copyAuthorization = await client.getCopyAuthorization("<destination model ID>");

// Finally, use the _source_ client to copy the model and await the copy operation
const poller = await sourceClient.beginCopyModelTo("<source model ID>");

// Model copying, like all other model creation operations, returns a poller that eventually produces a ModelDetails
// object
const modelDetails = await poller.pollUntilDone();

const {
  modelId, // identical to the modelId given when creating the copy authorization
  description, // identical to the description given when creating the copy authorization
  createdOn, // the Date (timestamp) that the model was created
  docTypes // information about the document types of the model (identical to the original, source model)
} = modelDetails;

Returns

a long-running operation (poller) that will eventually produce the copied model information or an error

Deletes a classifier with the given ID from the client's resource, if it exists. This operation CANNOT be reverted.

Example

await client.deleteDocumentClassifier("<classifier ID to delete>"));

Deletes a model with the given ID from the client's resource, if it exists. This operation CANNOT be reverted.

Example

await client.deleteDocumentModel("<model ID to delete>"));

Creates an authorization to copy a model into the resource, used with the beginCopyModelTo method.

The CopyAuthorization grants another cognitive service resource the right to create a model in this client's resource with the model ID and optional description that are encoded into the authorization.

Example

// The copyAuthorization data structure stored below grants any cognitive services resource the right to copy a
// model into the client's resource with the given destination model ID.
const copyAuthorization = await client.getCopyAuthorization("<destination model ID>");

Returns

a copy authorization that encodes the given modelId and optional description

Retrieves information about a classifier (DocumentClassifierDetails) by ID.

Example

const classifierId = "<classifier ID";

const {
  classifierId, // identical to the ID given when calling `getDocumentClassifier`
  description, // a textual description of the classifier, if provided during classifier creation
  createdOn, // the Date (timestamp) that the classifier was created
  // information about the document types in the classifier and their corresponding traning data
  docTypes
} = await client.getDocumentClassifier(classifierId);

// The `docTypes` property is a map of document type names to information about the training data
// for that document type.
for (const [docTypeName, classifierDocTypeDetails] of Object.entries(docTypes)) {
 console.log(`- '${docTypeName}': `, classifierDocTypeDetails);
}

Returns

information about the classifier with the given ID

Retrieves information about a model (DocumentModelDetails) by ID.

This method can retrieve information about custom as well as prebuilt models.

Breaking Change

In previous versions of the Form Recognizer REST API and SDK, the getModel method could return any model, even one that failed to create due to errors. In the new service versions, getDocumentModel and listDocumentModels only produce successfully created models (i.e. models that are "ready" for use). Failed models are now retrieved through the "operations" APIs, see getOperation and listOperations.

Example

// The ID of the prebuilt business card model
const modelId = "prebuilt-businessCard";

const {
  modelId, // identical to the modelId given when calling `getDocumentModel`
  description, // a textual description of the model, if provided during model creation
  createdOn, // the Date (timestamp) that the model was created
  // information about the document types in the model and their field schemas
  docTypes: {
    // the document type of the prebuilt business card model
    "prebuilt:businesscard": {
      // an optional, textual description of this document type
      description,
      // the schema of the fields in this document type, see the FieldSchema type
      fieldSchema,
      // the service's confidences in the fields (an object with field names as properties and numeric confidence
      // values)
      fieldConfidence
    }
  }
} = await client.getDocumentModel(modelId);

Returns

information about the model with the given ID

Retrieves information about an operation (OperationDetails) by its ID.

Operations represent non-analysis tasks, such as building, composing, or copying a model.

Returns

information about the operation with the given ID

Example

// The ID of the operation, which should be a GUID
const operationId = "<operation GUID>";

const {
  operationId, // identical to the operationId given when calling `getOperation`
  kind, // the operation kind, one of "documentModelBuild", "documentModelCompose", or "documentModelCopyTo"
  status, // the status of the operation, one of "notStarted", "running", "failed", "succeeded", or "canceled"
  percentCompleted, // a number between 0 and 100 representing the progress of the operation
  createdOn, // a Date object that reflects the time when the operation was started
  lastUpdatedOn, // a Date object that reflects the time when the operation state was last modified
} = await client.getOperation(operationId);

Retrieve basic information about this client's resource.

Example

const {
  // Information about the custom models in the current resource
  customDocumentModelDetails: {
    // The number of custom models in the current resource
    count,
    // The maximum number of models that the current resource can support
    limit
  }
} = await client.getResourceDetails();

Returns

basic information about this client's resource

List details about classifiers in the resource. This operation supports paging.

Examples

Async Iteration

for await (const details of client.listDocumentClassifiers()) {
  const {
    classifierId, // The classifier's unique ID
    description, // a textual description of the classifier, if provided during creation
    docTypes, // information about the document types in the classifier and their corresponding traning data
  } = details;
}

By Page

// The listDocumentClassifiers method is paged, and you can iterate by page using the `byPage` method.
const pages = client.listDocumentClassifiers().byPage();

for await (const page of pages) {
  // Each page is an array of classifiers and can be iterated synchronously
  for (const details of page) {
    const {
      classifierId, // The classifier's unique ID
      description, // a textual description of the classifier, if provided during creation
      docTypes, // information about the document types in the classifier and their corresponding traning data
    } = details;
  }
}

Returns

an async iterable of classifier details that supports paging

List summaries of models in the resource. Custom as well as prebuilt models will be included. This operation supports paging.

The model summary (DocumentModelSummary) includes only the basic information about the model, and does not include information about the document types in the model (such as the field schemas and confidence values).

To access the full information about the model, use getDocumentModel.

Breaking Change

In previous versions of the Form Recognizer REST API and SDK, the listModels method would return all models, even those that failed to create due to errors. In the new service versions, listDocumentModels and getDocumentModel only produce successfully created models (i.e. models that are "ready" for use). Failed models are now retrieved through the "operations" APIs, see getOperation and listOperations.

Examples

Async Iteration

for await (const summary of client.listDocumentModels()) {
  const {
    modelId, // The model's unique ID
    description, // a textual description of the model, if provided during model creation
  } = summary;

  // You can get the full model info using `getDocumentModel`
  const model = await client.getDocumentModel(modelId);
}

By Page

// The listDocumentModels method is paged, and you can iterate by page using the `byPage` method.
const pages = client.listDocumentModels().byPage();

for await (const page of pages) {
  // Each page is an array of models and can be iterated synchronously
  for (const model of page) {
    const {
      modelId, // The model's unique ID
      description, // a textual description of the model, if provided during model creation
    } = summary;

    // You can get the full model info using `getDocumentModel`
    const model = await client.getDocumentModel(modelId);
  }
}

Returns

an async iterable of model summaries that supports paging

List model creation operations in the resource. This will produce all operations, including operations that failed to create models successfully. This operation supports paging.

Examples

Async Iteration

for await (const operation of client.listOperations()) {
  const {
    operationId, // the operation's GUID
    status, // the operation status, one of "notStarted", "running", "succeeded", "failed", or "canceled"
    percentCompleted // the progress of the operation, from 0 to 100
  } = operation;
}

By Page

// The listOperations method is paged, and you can iterate by page using the `byPage` method.
const pages = client.listOperations().byPage();

for await (const page of pages) {
  // Each page is an array of operation info objects and can be iterated synchronously
  for (const operation of page) {
    const {
      operationId, // the operation's GUID
      status, // the operation status, one of "notStarted", "running", "succeeded", "failed", or "canceled"
      percentCompleted // the progress of the operation, from 0 to 100
    } = operation;
  }
}

Returns

an async iterable of operation information objects that supports paging