Options
All
  • Public
  • Public/Protected
  • All
Menu

Class DocumentModelAdministrationClient

Package version

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

Hierarchy

  • DocumentModelAdministrationClient

Index

Methods

beginBuildDocumentModel

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

    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)

    • Default value 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

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

    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

    • Default value 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

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

    Parameters

    Returns Promise<DocumentModelPoller>

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

deleteDocumentModel

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

    Example

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

    Parameters

    • modelId: string

      the unique ID of the model to delete from the resource

    • Default value options: DeleteDocumentModelOptions = {}

      optional settings for the request

    Returns Promise<void>

getCopyAuthorization

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

    Parameters

    • destinationModelId: string

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

    • Default value options: GetCopyAuthorizationOptions = {}

      optional settings for creating the copy authorization

    Returns Promise<CopyAuthorization>

    a copy authorization that encodes the given modelId and optional description

getDocumentModel

  • Retrieves information about a model ({@link ModelDetails}) 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);

    Parameters

    • modelId: string

      the unique ID of the model to query

    • Default value options: GetModelOptions = {}

      optional settings for the request

    Returns Promise<DocumentModelDetails>

    information about the model with the given ID

getOperation

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

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

    Parameters

    • operationId: string

      the ID of the operation to query

    • Default value 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

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

    Parameters

    Returns Promise<ResourceDetails>

    basic information about this client's resource

listDocumentModels

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

    The model summary ({@link ModelSummary}) 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);
      }
    }

    Parameters

    • Default value options: ListModelsOptions = {}

      optional settings for the model requests

    Returns PagedAsyncIterableIterator<DocumentModelSummary>

    an async iterable of model summaries that supports paging

listOperations

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

    Parameters

    Returns PagedAsyncIterableIterator<OperationSummary>

    an async iterable of operation information objects that supports paging

Generated using TypeDoc