Package com.azure.ai.formrecognizer.administration

Class DocumentModelAdministrationClient

java.lang.Object
com.azure.ai.formrecognizer.administration.DocumentModelAdministrationClient
public final class DocumentModelAdministrationClient extends Object
This class provides a synchronous client that contains model management the operations that apply to Azure Form Recognizer. Operations allowed by the client are creating, building of custom document analysis models, deleting models, listing models, copying a custom-built model to another Form Recognizer account, composing models from component models, getting operation information and getting account information.

Instantiating a synchronous Document Model Administration Client

 DocumentModelAdministrationClient documentModelAdministrationClient =
     new DocumentModelAdministrationClientBuilder().buildClient();
See Also:

  • Method Details

    • getDocumentAnalysisClient

      public DocumentAnalysisClient getDocumentAnalysisClient()
      Creates a new DocumentAnalysisClient object. The new DocumentAnalysisClient uses the same request policy pipeline as the DocumentAnalysisClient.
      Returns:
      A new DocumentAnalysisClient object.

    • beginBuildModel

      public SyncPoller<DocumentOperationResult,DocumentModelDetails> beginBuildModel(String trainingFilesUrl, DocumentModelBuildMode buildMode)
      Builds a custom document analysis model.

      Models are built using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', image/bmp. Other type of content is ignored.

      The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

      Code sample

       String trainingFilesUrl = "{SAS-URL-of-your-container-in-blob-storage}";
 DocumentModelDetails documentModelDetails
     = documentModelAdministrationClient.beginBuildModel(trainingFilesUrl,
         DocumentModelBuildMode.TEMPLATE)
     .getFinalResult();

 System.out.printf("Model ID: %s%n", documentModelDetails.getModelId());
 System.out.printf("Model Created on: %s%n", documentModelDetails.getCreatedOn());
 documentModelDetails.getDocTypes().forEach((key, docTypeInfo) -> {
     docTypeInfo.getFieldSchema().forEach((field, documentFieldSchema) -> {
         System.out.printf("Field: %s", field);
         System.out.printf("Field type: %s", documentFieldSchema.getType());
         System.out.printf("Field confidence: %.2f", docTypeInfo.getFieldConfidence().get(field));
     });
 });
      Parameters:
      trainingFilesUrl - an Azure Storage blob container's SAS URI. A container URI (without SAS) can be used if the container is public or has a managed identity configured. For more information on setting up a training data set, see: here.
      buildMode - the preferred technique for creating models. For faster training of models use DocumentModelBuildMode.TEMPLATE. See here for more information on building mode for custom documents.
      Returns:
      A SyncPoller that polls the building model operation until it has completed, has failed, or has been cancelled. The completed operation returns the trained custom document analysis model.
      Throws:
      DocumentModelOperationException - If building model fails with OperationStatus.FAILED is created.
      NullPointerException - If trainingFilesUrl is null.

    • beginBuildModel

      public SyncPoller<DocumentOperationResult,DocumentModelDetails> beginBuildModel(String trainingFilesUrl, DocumentModelBuildMode buildMode, BuildModelOptions buildModelOptions, Context context)
      Builds a custom document analysis model.

      Models are built using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', image/bmp. Other type of content is ignored.

      The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

      Code sample

       String trainingFilesUrl = "{SAS-URL-of-your-container-in-blob-storage}";
 String modelId = "custom-model-id";
 String prefix = "Invoice";
 Map<String, String> attrs = new HashMap<String, String>();
 attrs.put("createdBy", "sample");

 DocumentModelDetails documentModelDetails
     = documentModelAdministrationClient.beginBuildModel(trainingFilesUrl,
         DocumentModelBuildMode.TEMPLATE,
         new BuildModelOptions()
             .setModelId(modelId)
             .setDescription("model desc")
             .setPrefix(prefix)
             .setTags(attrs),
         Context.NONE)
     .getFinalResult();

 System.out.printf("Model ID: %s%n", documentModelDetails.getModelId());
 System.out.printf("Model Description: %s%n", documentModelDetails.getDescription());
 System.out.printf("Model Created on: %s%n", documentModelDetails.getCreatedOn());
 System.out.printf("Model assigned tags: %s%n", documentModelDetails.getTags());
 documentModelDetails.getDocTypes().forEach((key, docTypeInfo) -> {
     docTypeInfo.getFieldSchema().forEach((field, documentFieldSchema) -> {
         System.out.printf("Field: %s", field);
         System.out.printf("Field type: %s", documentFieldSchema.getType());
         System.out.printf("Field confidence: %.2f", docTypeInfo.getFieldConfidence().get(field));
     });
 });
      Parameters:
      trainingFilesUrl - an Azure Storage blob container's SAS URI. A container URI (without SAS) can be used if the container is public or has a managed identity configured. For more information on setting up a training data set, see: here.
      buildMode - the preferred technique for creating models. For faster training of models use DocumentModelBuildMode.TEMPLATE. See here for more information on building mode for custom documents.
      buildModelOptions - The configurable options to pass when building a custom document analysis model.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A SyncPoller that polls the building model operation until it has completed, has failed, or has been cancelled. The completed operation returns the built custom document analysis model.
      Throws:
      DocumentModelOperationException - If building the model fails with OperationStatus.FAILED is created.
      NullPointerException - If trainingFilesUrl is null.

    • getResourceDetails

      public ResourceDetails getResourceDetails()
      Get information about the current Form Recognizer resource.

      Code sample

       ResourceDetails resourceDetails = documentModelAdministrationClient.getResourceDetails();
 System.out.printf("Max number of models that can be build for this account: %d%n",
     resourceDetails.getDocumentModelLimit());
 System.out.printf("Current count of built document analysis models: %d%n",
     resourceDetails.getDocumentModelCount());
      Returns:
      The requested resource information details.

    • getResourceDetailsWithResponse

      public Response<ResourceDetails> getResourceDetailsWithResponse(Context context)
      Get information about the current Form recognizer resource with a Http response and a specified Context.

      Code sample

       Response<ResourceDetails> response =
     documentModelAdministrationClient.getResourceDetailsWithResponse(Context.NONE);
 System.out.printf("Response Status Code: %d.", response.getStatusCode());
 ResourceDetails resourceDetails = response.getValue();
 System.out.printf("Max number of models that can be build for this account: %d%n",
     resourceDetails.getDocumentModelLimit());
 System.out.printf("Current count of built document analysis models: %d%n",
     resourceDetails.getDocumentModelCount());
      Parameters:
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      The requested resource information details.

    • deleteModel

      public void deleteModel(String modelId)
      Deletes the specified custom document analysis model.

      Code sample

       String modelId = "{custom-model-id}";
 documentModelAdministrationClient.deleteModel(modelId);
 System.out.printf("Model ID: %s is deleted.%n", modelId);
      Parameters:
      modelId - The unique model identifier.
      Throws:
      IllegalArgumentException - If modelId is null or empty.

    • deleteModelWithResponse

      public Response<Void> deleteModelWithResponse(String modelId, Context context)
      Deletes the specified custom document analysis model.

      Code sample

       String modelId = "{custom-model-id}";
 Response<Void> response = documentModelAdministrationClient.deleteModelWithResponse(modelId, Context.NONE);
 System.out.printf("Response Status Code: %d.", response.getStatusCode());
 System.out.printf("Model ID: %s is deleted.%n", modelId);
      Parameters:
      modelId - The unique model identifier.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response containing containing status code and HTTP headers.
      Throws:
      IllegalArgumentException - If modelId is null or empty.

    • getCopyAuthorization

      public CopyAuthorization getCopyAuthorization()
      Generate authorization for copying a custom model into the target Form Recognizer resource.

      This should be called by the target resource (where the model will be copied to) and the output can be passed as the target parameter into beginCopyModelTo(String, CopyAuthorization).

      Returns:
      The CopyAuthorization

    • getCopyAuthorizationWithResponse

      public Response<CopyAuthorization> getCopyAuthorizationWithResponse(CopyAuthorizationOptions copyAuthorizationOptions, Context context)
      Generate authorization for copying a custom model into the target Form Recognizer resource.

      This should be called by the target resource (where the model will be copied to) and the output can be passed as the target parameter into beginCopyModelTo(String, CopyAuthorization).

      Parameters:
      copyAuthorizationOptions - The configurable options to pass when copying a model.
      context - Additional context that is passed through the Http pipeline during the service call.

      Code sample

       String modelId = "my-copied-model";
 Map<String, String> attrs = new HashMap<String, String>();
 attrs.put("createdBy", "sample");

 Response<CopyAuthorization> copyAuthorizationResponse =
     documentModelAdministrationClient.getCopyAuthorizationWithResponse(
         new CopyAuthorizationOptions()
             .setModelId(modelId)
             .setDescription("model-desc")
             .setTags(attrs),
         Context.NONE);

 System.out.printf("Copy Authorization operation returned with status: %s",
     copyAuthorizationResponse.getStatusCode());
 CopyAuthorization copyAuthorization = copyAuthorizationResponse.getValue();
 System.out.printf("Copy Authorization for model id: %s, access token: %s, "
         + "expiration time: %s, target resource ID; %s, target resource region: %s%n",
     copyAuthorization.getTargetModelId(),
     copyAuthorization.getAccessToken(),
     copyAuthorization.getExpiresOn(),
     copyAuthorization.getTargetResourceId(),
     copyAuthorization.getTargetResourceRegion()
 );
      Returns:
      A Response containing the CopyAuthorization

    • beginComposeModel

      public SyncPoller<DocumentOperationResult,DocumentModelDetails> beginComposeModel(List<String> componentModelIds)
      Create a composed model from the provided list of existing models in the account.

      This operations fails if the list consists of an invalid, non-existing model Id or duplicate IDs.

      The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

      Code sample

       String modelId1 = "{custom-model-id_1}";
 String modelId2 = "{custom-model-id_2}";
 final DocumentModelDetails documentModelDetails
     = documentModelAdministrationClient.beginComposeModel(Arrays.asList(modelId1, modelId2))
     .getFinalResult();

 System.out.printf("Model ID: %s%n", documentModelDetails.getModelId());
 System.out.printf("Model Description: %s%n", documentModelDetails.getDescription());
 System.out.printf("Model Created on: %s%n", documentModelDetails.getCreatedOn());
 documentModelDetails.getDocTypes().forEach((key, docTypeInfo) -> {
     docTypeInfo.getFieldSchema().forEach((field, documentFieldSchema) -> {
         System.out.printf("Field: %s", field);
         System.out.printf("Field type: %s", documentFieldSchema.getType());
         System.out.printf("Field confidence: %.2f", docTypeInfo.getFieldConfidence().get(field));
     });
 });
      Parameters:
      componentModelIds - The list of models IDs to form the composed model.
      Returns:
      A SyncPoller that polls the create composed model operation until it has completed, has failed, or has been cancelled. The completed operation returns the composed model.
      Throws:
      DocumentModelOperationException - If create composed model operation fails and model with OperationStatus.FAILED is created.
      NullPointerException - If the list of componentModelIds is null or empty.

    • beginComposeModel

      public SyncPoller<DocumentOperationResult,DocumentModelDetails> beginComposeModel(List<String> componentModelIds, ComposeModelOptions composeModelOptions, Context context)
      Create a composed model from the provided list of existing models in the account.

      This operations fails if the list consists of an invalid, non-existing model Id or duplicate IDs.

      The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

      Code sample

       String modelId1 = "{custom-model-id_1}";
 String modelId2 = "{custom-model-id_2}";
 String modelId = "my-composed-model";
 Map<String, String> attrs = new HashMap<String, String>();
 attrs.put("createdBy", "sample");

 final DocumentModelDetails documentModelDetails =
     documentModelAdministrationClient.beginComposeModel(Arrays.asList(modelId1, modelId2),
             new ComposeModelOptions()
                 .setModelId(modelId)
                 .setDescription("my composed model desc")
                 .setTags(attrs),
             Context.NONE)
         .setPollInterval(Duration.ofSeconds(5))
         .getFinalResult();

 System.out.printf("Model ID: %s%n", documentModelDetails.getModelId());
 System.out.printf("Model Description: %s%n", documentModelDetails.getDescription());
 System.out.printf("Model Created on: %s%n", documentModelDetails.getCreatedOn());
 System.out.printf("Model assigned tags: %s%n", documentModelDetails.getTags());
 documentModelDetails.getDocTypes().forEach((key, docTypeInfo) -> {
     docTypeInfo.getFieldSchema().forEach((field, documentFieldSchema) -> {
         System.out.printf("Field: %s", field);
         System.out.printf("Field type: %s", documentFieldSchema.getType());
         System.out.printf("Field confidence: %.2f", docTypeInfo.getFieldConfidence().get(field));
     });
 });
      Parameters:
      componentModelIds - The list of models IDs to form the composed model.
      composeModelOptions - The configurable options to pass when creating a composed model.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A SyncPoller that polls the create composed model operation until it has completed, has failed, or has been cancelled. The completed operation returns the composed model.
      Throws:
      DocumentModelOperationException - If create composed model operation fails and model with OperationStatus.FAILED is created.
      NullPointerException - If the list of componentModelIds is null or empty.

    • beginCopyModelTo

      public SyncPoller<DocumentOperationResult,DocumentModelDetails> beginCopyModelTo(String modelId, CopyAuthorization target)
      Copy a custom model stored in this resource (the source) to the user specified target Form Recognizer resource.

      This should be called with the source Form Recognizer resource (with the model that is intended to be copied). The target parameter should be supplied from the target resource's output from getCopyAuthorization() method.

      The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

      Code sample

       String copyModelId = "copy-model";
 // Get authorization to copy the model to target resource
 CopyAuthorization copyAuthorization = documentModelAdministrationClient.getCopyAuthorization();
 // Start copy operation from the source client
 DocumentModelDetails documentModelDetails =
     documentModelAdministrationClient.beginCopyModelTo(copyModelId, copyAuthorization).getFinalResult();
 System.out.printf("Copied model has model ID: %s, was created on: %s.%n,",
     documentModelDetails.getModelId(),
     documentModelDetails.getCreatedOn());
      Parameters:
      modelId - Model identifier of the model to copy to target resource.
      target - the copy authorization to the target Form Recognizer resource. The copy authorization can be generated from the target resource's call to getCopyAuthorization()
      Returns:
      A SyncPoller that polls the copy model operation until it has completed, has failed, or has been cancelled.

    • beginCopyModelTo

      public SyncPoller<DocumentOperationResult,DocumentModelDetails> beginCopyModelTo(String modelId, CopyAuthorization target, Context context)
      Copy a custom model stored in this resource (the source) to the user specified target Form Recognizer resource.

      This should be called with the source Form Recognizer resource (with the model that is intended to be copied). The target parameter should be supplied from the target resource's output from getCopyAuthorization() method.

      The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

      Code sample

       String copyModelId = "copy-model";
 // Get authorization to copy the model to target resource
 CopyAuthorization copyAuthorization = documentModelAdministrationClient.getCopyAuthorization();
 // Start copy operation from the source client
 DocumentModelDetails documentModelDetails =
     documentModelAdministrationClient.beginCopyModelTo(copyModelId, copyAuthorization, Context.NONE).getFinalResult();
 System.out.printf("Copied model has model ID: %s, was created on: %s.%n,",
     documentModelDetails.getModelId(),
     documentModelDetails.getCreatedOn());
      Parameters:
      modelId - Model identifier of the model to copy to target resource.
      target - the copy authorization to the target Form Recognizer resource. The copy authorization can be generated from the target resource's call to getCopyAuthorization().
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A SyncPoller that polls the copy model operation until it has completed, has failed, or has been cancelled.

    • listModels

      public PagedIterable<DocumentModelSummary> listModels()
      List information for each model on the Form Recognizer account that were built successfully.

      Code sample

       documentModelAdministrationClient.listModels()
     .forEach(documentModel ->
         System.out.printf("Model ID: %s, Model description: %s, Created on: %s.%n",
             documentModel.getModelId(),
             documentModel.getDescription(),
             documentModel.getCreatedOn())
     );
      Returns:
      PagedIterable of DocumentModelSummary custom form model information.

    • listModels

      public PagedIterable<DocumentModelSummary> listModels(Context context)
      List information for each model on the Form Recognizer account that were built successfully with a Http response and a specified Context.

      Code sample

       documentModelAdministrationClient.listModels(Context.NONE)
     .forEach(documentModel ->
         System.out.printf("Model ID: %s, Model description: %s, Created on: %s.%n",
             documentModel.getModelId(),
             documentModel.getDescription(),
             documentModel.getCreatedOn())
     );
      Parameters:
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      PagedIterable of DocumentModelSummary custom form model information.

    • getModel

      public DocumentModelDetails getModel(String modelId)
      Get detailed information for a specified model ID.

      Code sample

       String modelId = "{custom-model-id}";
 DocumentModelDetails documentModelDetails = documentModelAdministrationClient.getModel(modelId);
 System.out.printf("Model ID: %s%n", documentModelDetails.getModelId());
 System.out.printf("Model Description: %s%n", documentModelDetails.getDescription());
 System.out.printf("Model Created on: %s%n", documentModelDetails.getCreatedOn());
 documentModelDetails.getDocTypes().forEach((key, docTypeInfo) -> {
     docTypeInfo.getFieldSchema().forEach((field, documentFieldSchema) -> {
         System.out.printf("Field: %s", field);
         System.out.printf("Field type: %s", documentFieldSchema.getType());
         System.out.printf("Field confidence: %.2f", docTypeInfo.getFieldConfidence().get(field));
     });
 });
      Parameters:
      modelId - The unique model identifier.
      Returns:
      The detailed information for the specified model.
      Throws:
      IllegalArgumentException - If modelId is null or empty.

    • getModelWithResponse

      public Response<DocumentModelDetails> getModelWithResponse(String modelId, Context context)
      Get detailed information for a specified model ID.

      Code sample

       String modelId = "{custom-model-id}";
 Response<DocumentModelDetails> response = documentModelAdministrationClient.getModelWithResponse(modelId, Context.NONE);
 System.out.printf("Response Status Code: %d.", response.getStatusCode());
 DocumentModelDetails documentModelDetails = response.getValue();
 System.out.printf("Model ID: %s%n", documentModelDetails.getModelId());
 System.out.printf("Model Description: %s%n", documentModelDetails.getDescription());
 System.out.printf("Model Created on: %s%n", documentModelDetails.getCreatedOn());
 documentModelDetails.getDocTypes().forEach((key, docTypeInfo) -> {
     docTypeInfo.getFieldSchema().forEach((field, documentFieldSchema) -> {
         System.out.printf("Field: %s", field);
         System.out.printf("Field type: %s", documentFieldSchema.getType());
         System.out.printf("Field confidence: %.2f", docTypeInfo.getFieldConfidence().get(field));
     });
 });
      Parameters:
      modelId - The unique model identifier.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      The detailed information for the specified model.
      Throws:
      IllegalArgumentException - If modelId is null or empty.

    • getOperation

      public ModelOperationDetails getOperation(String operationId)
      Get detailed operation information for the specified ID with Http response.

      This operations fails if the operation ID used is past 24 hours.

      Code sample

       String operationId = "{operation-id}";
 ModelOperationDetails modelOperationDetails = documentModelAdministrationClient.getOperation(operationId);
 System.out.printf("Operation ID: %s%n", modelOperationDetails.getOperationId());
 System.out.printf("Operation Kind: %s%n", modelOperationDetails.getKind());
 System.out.printf("Operation Status: %s%n", modelOperationDetails.getStatus());
 System.out.printf("Model ID created with this operation: %s%n", modelOperationDetails.getModelId());
 if (ModelOperationStatus.FAILED.equals(modelOperationDetails.getStatus())) {
     System.out.printf("Operation fail error: %s%n", modelOperationDetails.getError().getMessage());
 }
      Parameters:
      operationId - Unique operation ID.
      Returns:
      The detailed information for the specified operation.
      Throws:
      IllegalArgumentException - If operationId is null or empty.

    • getOperationWithResponse

      public Response<ModelOperationDetails> getOperationWithResponse(String operationId, Context context)
      Get detailed operation information for the specified ID with Http response.

      This operations fails if the operation ID used is past 24 hours.

      Code sample

       String operationId = "{operation-id}";
 Response<ModelOperationDetails> response =
     documentModelAdministrationClient.getOperationWithResponse(operationId, Context.NONE);
 System.out.printf("Response Status Code: %d.", response.getStatusCode());
 ModelOperationDetails modelOperationDetails = response.getValue();
 System.out.printf("Operation ID: %s%n", modelOperationDetails.getOperationId());
 System.out.printf("Operation Kind: %s%n", modelOperationDetails.getKind());
 System.out.printf("Operation Status: %s%n", modelOperationDetails.getStatus());
 System.out.printf("Model ID created with this operation: %s%n", modelOperationDetails.getModelId());
 if (ModelOperationStatus.FAILED.equals(modelOperationDetails.getStatus())) {
     System.out.printf("Operation fail error: %s%n", modelOperationDetails.getError().getMessage());
 }
      Parameters:
      operationId - Unique operation ID.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      The detailed information for the specified operation.
      Throws:
      IllegalArgumentException - If operationId is null or empty.

    • listOperations

      public PagedIterable<ModelOperationSummary> listOperations()
      List information for each model operation on the Form Recognizer account in the past 24 hours.

      Code sample

       PagedIterable<ModelOperationSummary>
     modelOperationInfo = documentModelAdministrationClient.listOperations();
 modelOperationInfo.forEach(modelOperationSummary -> {
     System.out.printf("Operation ID: %s%n", modelOperationSummary.getOperationId());
     System.out.printf("Operation Status: %s%n", modelOperationSummary.getStatus());
     System.out.printf("Operation Created on: %s%n", modelOperationSummary.getCreatedOn());
     System.out.printf("Operation Percent completed: %d%n", modelOperationSummary.getPercentCompleted());
     System.out.printf("Operation Kind: %s%n", modelOperationSummary.getKind());
     System.out.printf("Operation Last updated on: %s%n", modelOperationSummary.getLastUpdatedOn());
     System.out.printf("Operation resource location: %s%n", modelOperationSummary.getResourceLocation());
 });
      Returns:
      PagedIterable of ModelOperationSummary custom form model information.

    • listOperations

      public PagedIterable<ModelOperationSummary> listOperations(Context context)
      List information for each operation on the Form Recognizer account in the past 24 hours with an HTTP response and a specified Context.

      Code sample

       PagedIterable<ModelOperationSummary>
     modelOperationInfo = documentModelAdministrationClient.listOperations(Context.NONE);
 modelOperationInfo.forEach(modelOperationSummary -> {
     System.out.printf("Operation ID: %s%n", modelOperationSummary.getOperationId());
     System.out.printf("Operation Status: %s%n", modelOperationSummary.getStatus());
     System.out.printf("Operation Created on: %s%n", modelOperationSummary.getCreatedOn());
     System.out.printf("Operation Percent completed: %d%n", modelOperationSummary.getPercentCompleted());
     System.out.printf("Operation Kind: %s%n", modelOperationSummary.getKind());
     System.out.printf("Operation Last updated on: %s%n", modelOperationSummary.getLastUpdatedOn());
     System.out.printf("Operation resource location: %s%n", modelOperationSummary.getResourceLocation());
 });
      Parameters:
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      PagedIterable of ModelOperationSummary custom form model information.