DocumentModelAdministrationClient class
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
| Document |
Create a DocumentModelAdministrationClient instance from a resource endpoint and a static API key
( Example: |
| Document |
Create a DocumentModelAdministrationClient instance from a resource endpoint and a an Azure Identity See the Example: |
Methods
| begin |
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:
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 |
| begin |
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 |
| begin |
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 |
| begin |
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 |
| begin |
Copies a model with the given ID into the resource and model ID encoded by a given copy authorization. See CopyAuthorization and getCopyAuthorization. Example |
| delete |
Deletes a classifier with the given ID from the client's resource, if it exists. This operation CANNOT be reverted. Example |
| delete |
Deletes a model with the given ID from the client's resource, if it exists. This operation CANNOT be reverted. Example |
| get |
Creates an authorization to copy a model into the resource, used with the The Example |
| get |
Retrieves information about a classifier (DocumentClassifierDetails) by ID. Example |
| get |
Retrieves information about a model (DocumentModelDetails) by ID. This method can retrieve information about custom as well as prebuilt models. Breaking ChangeIn previous versions of the Form Recognizer REST API and SDK, the Example |
| get |
Retrieves information about an operation ( Operations represent non-analysis tasks, such as building, composing, or copying a model. |
| get |
Retrieve basic information about this client's resource. Example |
| list |
List details about classifiers in the resource. This operation supports paging. ExamplesAsync IterationBy Page |
| list |
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 ChangeIn previous versions of the Form Recognizer REST API and SDK, the ExamplesAsync IterationBy Page |
| list |
List model creation operations in the resource. This will produce all operations, including operations that failed to create models successfully. This operation supports paging. ExamplesAsync IterationBy Page |
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
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
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 toazureBlobSourcebut 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)
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.
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;
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
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
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
an async iterable of operation information objects that supports paging