DocumentModelAdministrationClient class

Reference

Package:: @azure/ai-form-recognizer

A client for interacting with the Form Recognizer service's model management features, such as creating, reading, listing, deleting, and copying models.

Examples:

Azure Active Directory

import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new DefaultAzureCredential();

const client = new DocumentModelAdministrationClient(endpoint, credential);

API Key (Subscription Key)

import { DocumentModelAdministrationClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new AzureKeyCredential("<api key>");

const client = new DocumentModelAdministrationClient(endpoint, credential);

Constructors

DocumentModelAdministrationClient(string, KeyCredential, DocumentModelAdministrationClientOptions)

Create a DocumentModelAdministrationClient instance from a resource endpoint and a static API key (KeyCredential),

Example:

import { DocumentModelAdministrationClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new AzureKeyCredential("<api key>");

const client = new DocumentModelAdministrationClient(endpoint, credential);

DocumentModelAdministrationClient(string, TokenCredential, DocumentModelAdministrationClientOptions)

Create a DocumentModelAdministrationClient instance from a resource endpoint and a an Azure Identity TokenCredential.

See the @azure/identity package for more information about authenticating with Azure Active Directory.

Example:

import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new DefaultAzureCredential();

const client = new DocumentModelAdministrationClient(endpoint, credential);

Methods

beginBuildDocumentClassifier(string, DocumentClassifierDocumentTypeSources, BeginBuildDocumentClassifierOptions)	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;
beginBuildDocumentModel(string, DocumentModelSource, DocumentModelBuildMode, BeginBuildDocumentModelOptions)	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 <xref: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;
beginBuildDocumentModel(string, string, DocumentModelBuildMode, BeginBuildDocumentModelOptions)	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;
beginComposeDocumentModel(string, Iterable<string>, BeginComposeDocumentModelOptions)	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;
beginCopyModelTo(string, CopyAuthorization, BeginCopyModelOptions)	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;
deleteDocumentClassifier(string, OperationOptions)	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>"));`
deleteDocumentModel(string, DeleteDocumentModelOptions)	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>"));`
getCopyAuthorization(string, GetCopyAuthorizationOptions)	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>");`
getDocumentClassifier(string, OperationOptions)	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); }
getDocumentModel(string, GetModelOptions)	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);
getOperation(string, GetOperationOptions)	Retrieves information about an operation (`OperationDetails`) by its ID. Operations represent non-analysis tasks, such as building, composing, or copying a model.
getResourceDetails(GetResourceDetailsOptions)	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();`
listDocumentClassifiers(ListModelsOptions)	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; } }
listDocumentModels(ListModelsOptions)	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); } }
listOperations(ListOperationsOptions)	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; } }

Constructor Details

DocumentModelAdministrationClient(string, KeyCredential, DocumentModelAdministrationClientOptions)

Create a DocumentModelAdministrationClient instance from a resource endpoint and a static API key (KeyCredential),

Example:

import { DocumentModelAdministrationClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new AzureKeyCredential("<api key>");

const client = new DocumentModelAdministrationClient(endpoint, credential);

new DocumentModelAdministrationClient(endpoint: string, credential: KeyCredential, options?: DocumentModelAdministrationClientOptions)

Parameters

endpoint: string

the endpoint URL of an Azure Cognitive Services instance

credential: KeyCredential

a KeyCredential containing the Cognitive Services instance subscription key

options: DocumentModelAdministrationClientOptions

optional settings for configuring all methods in the client

DocumentModelAdministrationClient(string, TokenCredential, DocumentModelAdministrationClientOptions)

Create a DocumentModelAdministrationClient instance from a resource endpoint and a an Azure Identity TokenCredential.

See the @azure/identity package for more information about authenticating with Azure Active Directory.

Example:

import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<resource name>.cognitiveservices.azure.com";
const credential = new DefaultAzureCredential();

const client = new DocumentModelAdministrationClient(endpoint, credential);

new DocumentModelAdministrationClient(endpoint: string, credential: TokenCredential, options?: DocumentModelAdministrationClientOptions)

Parameters

endpoint: string

the endpoint URL of an Azure Cognitive Services instance

credential: TokenCredential

a TokenCredential instance from the @azure/identity package

options: DocumentModelAdministrationClientOptions

optional settings for configuring all methods in the client

Method Details

beginBuildDocumentClassifier(string, DocumentClassifierDocumentTypeSources, BeginBuildDocumentClassifierOptions)

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;

function beginBuildDocumentClassifier(classifierId: string, docTypeSources: DocumentClassifierDocumentTypeSources, options?: BeginBuildDocumentClassifierOptions): Promise<DocumentClassifierPoller>

Parameters

classifierId: string

the unique ID of the classifier to create

docTypeSources: DocumentClassifierDocumentTypeSources

the document types to include in the classifier and their sources (a map of document type names to ClassifierDocumentTypeDetails)

options: BeginBuildDocumentClassifierOptions

optional settings for the classifier build operation

Returns

Promise<DocumentClassifierPoller>

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

beginBuildDocumentModel(string, DocumentModelSource, DocumentModelBuildMode, BeginBuildDocumentModelOptions)

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 <xref: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;

function beginBuildDocumentModel(modelId: string, contentSource: DocumentModelSource, buildMode: DocumentModelBuildMode, options?: BeginBuildDocumentModelOptions): Promise<DocumentModelPoller>

Parameters

modelId: string

the unique ID of the model to create

contentSource: DocumentModelSource

a content source that provides the training data for this model

buildMode: DocumentModelBuildMode

the mode to use when building the model (see DocumentModelBuildMode)

options: BeginBuildDocumentModelOptions

optional settings for the model build operation

Returns

Promise<DocumentModelPoller>

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

beginBuildDocumentModel(string, string, DocumentModelBuildMode, BeginBuildDocumentModelOptions)

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

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;

function beginBuildDocumentModel(modelId: string, containerUrl: string, buildMode: DocumentModelBuildMode, options?: BeginBuildDocumentModelOptions): Promise<DocumentModelPoller>

Parameters

modelId: string

the unique ID of the model to create

containerUrl: string

SAS-encoded URL to an Azure Storage container holding the training data set

buildMode: DocumentModelBuildMode

the mode to use when building the model (see DocumentModelBuildMode)

options: BeginBuildDocumentModelOptions

optional settings for the model build operation

Returns

Promise<DocumentModelPoller>

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

beginComposeDocumentModel(string, Iterable<string>, BeginComposeDocumentModelOptions)

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;

function beginComposeDocumentModel(modelId: string, componentModelIds: Iterable<string>, options?: BeginComposeDocumentModelOptions): Promise<DocumentModelPoller>

Parameters

modelId: string

the unique ID of the model to create

componentModelIds: Iterable<string>

an Iterable of strings representing the unique model IDs of the models to compose

options: BeginComposeDocumentModelOptions

optional settings for model creation

Returns

Promise<DocumentModelPoller>

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

beginCopyModelTo(string, CopyAuthorization, BeginCopyModelOptions)

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;

function beginCopyModelTo(sourceModelId: string, authorization: CopyAuthorization, options?: BeginCopyModelOptions): Promise<DocumentModelPoller>

Parameters

sourceModelId: string

the unique ID of the source model that will be copied

authorization: CopyAuthorization

an authorization to copy the model, created using the getCopyAuthorization

options: BeginCopyModelOptions

optional settings for

Returns

Promise<DocumentModelPoller>

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

deleteDocumentClassifier(string, OperationOptions)

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>"));

function deleteDocumentClassifier(classifierId: string, options?: OperationOptions): Promise<void>

Parameters

classifierId: string

the unique ID of the classifier to delete from the resource

options: OperationOptions

optional settings for the request

Returns

Promise<void>

deleteDocumentModel(string, DeleteDocumentModelOptions)

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>"));

function deleteDocumentModel(modelId: string, options?: DeleteDocumentModelOptions): Promise<void>

Parameters

modelId: string

the unique ID of the model to delete from the resource

options: DeleteDocumentModelOptions

optional settings for the request

Returns

Promise<void>

getCopyAuthorization(string, GetCopyAuthorizationOptions)

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>");

function getCopyAuthorization(destinationModelId: string, options?: GetCopyAuthorizationOptions): Promise<CopyAuthorization>

Parameters

destinationModelId: string

the unique ID of the destination model (the ID to copy the model into)

options: GetCopyAuthorizationOptions

optional settings for creating the copy authorization

Returns

Promise<CopyAuthorization>

a copy authorization that encodes the given modelId and optional description

getDocumentClassifier(string, OperationOptions)

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);
}

function getDocumentClassifier(classifierId: string, options?: OperationOptions): Promise<DocumentClassifierDetails>

Parameters

classifierId: string

the unique ID of the classifier to query

options: OperationOptions

optional settings for the request

Returns

Promise<DocumentClassifierDetails>

information about the classifier with the given ID

getDocumentModel(string, GetModelOptions)

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);

function getDocumentModel(modelId: string, options?: GetModelOptions): Promise<DocumentModelDetails>

Parameters

modelId: string

the unique ID of the model to query

options: GetModelOptions

optional settings for the request

Returns

Promise<DocumentModelDetails>

information about the model with the given ID

getOperation(string, GetOperationOptions)

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

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

function getOperation(operationId: string, options?: GetOperationOptions): Promise<OperationDetails>

Parameters

operationId: string

the ID of the operation to query

options: GetOperationOptions

optional settings for the request

Returns

Promise<OperationDetails>

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);

getResourceDetails(GetResourceDetailsOptions)

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();

function getResourceDetails(options?: GetResourceDetailsOptions): Promise<ResourceDetails>

Parameters

options: GetResourceDetailsOptions

optional settings for the request

Returns

Promise<ResourceDetails>

basic information about this client's resource

listDocumentClassifiers(ListModelsOptions)

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;
  }
}

function listDocumentClassifiers(options?: ListModelsOptions): PagedAsyncIterableIterator<DocumentClassifierDetails, DocumentClassifierDetails[], PageSettings>

Parameters

options: ListModelsOptions

optional settings for the classifier requests

Returns

PagedAsyncIterableIterator<DocumentClassifierDetails, DocumentClassifierDetails[], PageSettings>

an async iterable of classifier details that supports paging

listDocumentModels(ListModelsOptions)

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);
  }
}

function listDocumentModels(options?: ListModelsOptions): PagedAsyncIterableIterator<DocumentModelSummary, DocumentModelSummary[], PageSettings>

Parameters

options: ListModelsOptions

optional settings for the model requests

Returns

PagedAsyncIterableIterator<DocumentModelSummary, DocumentModelSummary[], PageSettings>

an async iterable of model summaries that supports paging

listOperations(ListOperationsOptions)

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;
  }
}

function listOperations(options?: ListOperationsOptions): PagedAsyncIterableIterator<OperationSummary, OperationSummary[], PageSettings>

Parameters

options: ListOperationsOptions

optional settings for the operation requests

Returns

PagedAsyncIterableIterator<OperationSummary, OperationSummary[], PageSettings>

an async iterable of operation information objects that supports paging