azure.ai.formrecognizer.DocumentModelAdministrationClient.yml

### YamlMime:PythonClass
uid: azure.ai.formrecognizer.DocumentModelAdministrationClient
name: DocumentModelAdministrationClient
fullName: azure.ai.formrecognizer.DocumentModelAdministrationClient
module: azure.ai.formrecognizer
inheritances:
- azure.ai.formrecognizer._form_base_client.FormRecognizerClientBase
summary: 'DocumentModelAdministrationClient is the Form Recognizer interface to use
  for building

  and managing models.


  It provides methods for building models, as well as methods for viewing and deleting
  models,

  viewing model operations, accessing account information, copying models to another

  Form Recognizer resource, and composing a new model from a collection of existing
  models.


  > [!NOTE]

  > DocumentModelAdministrationClient should be used with API versions

  >

  > 2022-08-31 and up. To use API versions <=v2.1, instantiate a FormTrainingClient.

  >


  New in version 2022-08-31: The *DocumentModelAdministrationClient* and its client
  methods.'
constructor:
  syntax: 'DocumentModelAdministrationClient(endpoint: str, credential: AzureKeyCredential
    | TokenCredential, **kwargs: Any)'
  parameters:
  - name: endpoint
    description: 'Supported Cognitive Services endpoints (protocol and hostname,

      for example: [https://westus2.api.cognitive.microsoft.com](https://westus2.api.cognitive.microsoft.com)).'
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: 'Credentials needed for the client to connect to Azure.

      This is an instance of AzureKeyCredential if using an API key or a token

      credential from <xref:azure.identity>.'
    isRequired: true
    types:
    - <xref:azure.core.credentials.AzureKeyCredential>
    - <xref:azure.core.credentials.TokenCredential>
  - name: api_version
    description: 'The API version of the service to use for requests. It defaults
      to the latest service version.

      Setting to an older version may result in reduced feature compatibility. To
      use API versions

      <=v2.1, instantiate a FormTrainingClient.'
    types:
    - <xref:str>
    - <xref:azure.ai.formrecognizer.DocumentAnalysisApiVersion>
methods:
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.begin_build_document_model
  name: begin_build_document_model
  summary: 'Build a custom document model.


    The request must include a *blob_container_url* keyword parameter that is an

    externally accessible Azure storage blob container URI (preferably a Shared Access
    Signature URI). Note that

    a container URI (without SAS) is accepted only when the container is public or
    has a managed identity

    configured, see more about configuring managed identities to work with Form Recognizer
    here:

    [https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities](https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities).

    Models are built using documents that are of the following content type - ''application/pdf'',

    ''image/jpeg'', ''image/png'', ''image/tiff'', ''image/bmp'', or ''image/heif''.
    Other types of content in the container

    is ignored.'
  signature: 'begin_build_document_model(build_mode: str | ModelBuildMode, *, blob_container_url:
    str, **kwargs: Any) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]'
  parameters:
  - name: build_mode
    description: 'The custom model build mode. Possible values include: "template",
      "neural".

      For more information about build modes, see: [https://aka.ms/azsdk/formrecognizer/buildmode](https://aka.ms/azsdk/formrecognizer/buildmode).'
    isRequired: true
    types:
    - <xref:str>
    - <xref:azure.ai.formrecognizer.ModelBuildMode>
  - name: blob_container_url
    description: '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: [https://aka.ms/azsdk/formrecognizer/buildtrainingset](https://aka.ms/azsdk/formrecognizer/buildtrainingset).'
    types:
    - <xref:str>
  - name: model_id
    description: A unique ID for your model. If not specified, a model ID will be
      created for you.
    types:
    - <xref:str>
  - name: description
    description: An optional description to add to the model.
    types:
    - <xref:str>
  - name: prefix
    description: 'A case-sensitive prefix string to filter documents in the blob container
      url path.

      For example, when using an Azure storage blob URI, use the prefix to restrict
      sub folders.

      *prefix* should end in ''/'' to avoid cases where filenames share the same prefix.'
    types:
    - <xref:str>
  - name: tags
    description: List of user defined key-value tag attributes associated with the
      model.
    types:
    - <xref:dict>[<xref:str>, <xref:str>]
  return:
    description: 'An instance of an DocumentModelAdministrationLROPoller. Call *result()*
      on the poller

      object to return a <xref:azure.ai.formrecognizer.DocumentModelDetails>.'
    types:
    - <xref:azure.ai.formrecognizer.DocumentModelAdministrationLROPoller>[<xref:azure.ai.formrecognizer.DocumentModelDetails>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.begin_compose_document_model
  name: begin_compose_document_model
  summary: 'Creates a composed document model from a collection of existing models.


    A composed model allows multiple models to be called with a single model ID. When
    a document is

    submitted to be analyzed with a composed model ID, a classification step is first
    performed to

    route it to the correct custom model.'
  signature: 'begin_compose_document_model(component_model_ids: List[str], **kwargs:
    Any) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]'
  parameters:
  - name: component_model_ids
    description: List of model IDs to use in the composed model.
    isRequired: true
    types:
    - <xref:list>[<xref:str>]
  - name: model_id
    description: 'A unique ID for your composed model.

      If not specified, a model ID will be created for you.'
    types:
    - <xref:str>
  - name: description
    description: An optional description to add to the model.
    types:
    - <xref:str>
  - name: tags
    description: List of user defined key-value tag attributes associated with the
      model.
    types:
    - <xref:dict>[<xref:str>, <xref:str>]
  return:
    description: 'An instance of an DocumentModelAdministrationLROPoller. Call *result()*
      on the poller

      object to return a <xref:azure.ai.formrecognizer.DocumentModelDetails>.'
    types:
    - <xref:azure.ai.formrecognizer.DocumentModelAdministrationLROPoller>[<xref:azure.ai.formrecognizer.DocumentModelDetails>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.begin_copy_document_model_to
  name: begin_copy_document_model_to
  summary: 'Copy a document 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 calling the <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient.get_copy_authorization>
    method.'
  signature: 'begin_copy_document_model_to(model_id: str, target: TargetAuthorization,
    **kwargs: Any) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]'
  parameters:
  - name: model_id
    description: Model identifier of the model to copy to target resource.
    isRequired: true
    types:
    - <xref:str>
  - name: target
    description: 'The copy authorization generated from the target resource''s call
      to

      <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient.get_copy_authorization>.'
    isRequired: true
    types:
    - <xref:azure.ai.formrecognizer.TargetAuthorization>
  return:
    description: 'An instance of a DocumentModelAdministrationLROPoller. Call *result()*
      on the poller

      object to return a <xref:azure.ai.formrecognizer.DocumentModelDetails>.'
    types:
    - <xref:azure.ai.formrecognizer.DocumentModelAdministrationLROPoller>[<xref:azure.ai.formrecognizer.DocumentModelDetails>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.close
  name: close
  summary: Close the <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient>
    session.
  signature: close() -> None
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.delete_document_model
  name: delete_document_model
  summary: Delete a custom document model.
  signature: 'delete_document_model(model_id: str, **kwargs: Any) -> None'
  parameters:
  - name: model_id
    description: Model identifier.
    isRequired: true
    types:
    - <xref:str>
  return:
    types:
    - <xref:None>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
  - type: azure.core.exceptions.ResourceNotFoundError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.get_copy_authorization
  name: get_copy_authorization
  summary: '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 <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient.begin_copy_document_model_to>.'
  signature: 'get_copy_authorization(**kwargs: Any) -> TargetAuthorization'
  parameters:
  - name: model_id
    description: 'A unique ID for your copied model.

      If not specified, a model ID will be created for you.'
    types:
    - <xref:str>
  - name: description
    description: An optional description to add to the model.
    types:
    - <xref:str>
  - name: tags
    description: List of user defined key-value tag attributes associated with the
      model.
    types:
    - <xref:dict>[<xref:str>, <xref:str>]
  return:
    description: A dictionary with values necessary for the copy authorization.
    types:
    - <xref:azure.ai.formrecognizer.TargetAuthorization>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.get_document_analysis_client
  name: get_document_analysis_client
  summary: Get an instance of a DocumentAnalysisClient from DocumentModelAdministrationClient.
  signature: 'get_document_analysis_client(**kwargs: Any) -> DocumentAnalysisClient'
  return:
    description: A DocumentAnalysisClient
    types:
    - <xref:azure.ai.formrecognizer.DocumentAnalysisClient>
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.get_document_model
  name: get_document_model
  summary: Get a document model by its ID.
  signature: 'get_document_model(model_id: str, **kwargs: Any) -> DocumentModelDetails'
  parameters:
  - name: model_id
    description: Model identifier.
    isRequired: true
    types:
    - <xref:str>
  return:
    description: DocumentModelDetails
    types:
    - <xref:azure.ai.formrecognizer.DocumentModelDetails>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
  - type: azure.core.exceptions.ResourceNotFoundError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.get_operation
  name: get_operation
  summary: 'Get an operation by its ID.


    Get an operation associated with the Form Recognizer resource.

    Note that operation information only persists for 24 hours. If the document model
    operation was successful,

    the model can be accessed using the <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient.get_document_model>
    or <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient.list_document_models>
    APIs.'
  signature: 'get_operation(operation_id: str, **kwargs: Any) -> OperationDetails'
  parameters:
  - name: operation_id
    description: The operation ID.
    isRequired: true
    types:
    - <xref:str>
  return:
    description: OperationDetails
    types:
    - <xref:azure.ai.formrecognizer.OperationDetails>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.get_resource_details
  name: get_resource_details
  summary: Get information about the models under the Form Recognizer resource.
  signature: 'get_resource_details(**kwargs: Any) -> ResourceDetails'
  return:
    description: Summary of custom models under the resource - model count and limit.
    types:
    - <xref:azure.ai.formrecognizer.ResourceDetails>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.list_document_models
  name: list_document_models
  summary: 'List information for each model, including its model ID,

    description, and when it was created.'
  signature: 'list_document_models(**kwargs: Any) -> ItemPaged[DocumentModelSummary]'
  return:
    description: Pageable of DocumentModelSummary.
    types:
    - <xref:azure.core.paging.ItemPaged>[<xref:azure.ai.formrecognizer.DocumentModelSummary>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.DocumentModelAdministrationClient.list_operations
  name: list_operations
  summary: 'List information for each operation.


    Lists all operations associated with the Form Recognizer resource.

    Note that operation information only persists for 24 hours. If a document model
    operation was successful,

    the document model can be accessed using the <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient.get_document_model>
    or <xref:azure.ai.formrecognizer.DocumentModelAdministrationClient.list_document_models>
    APIs.'
  signature: 'list_operations(**kwargs: Any) -> ItemPaged[OperationSummary]'
  return:
    description: A pageable of OperationSummary.
    types:
    - <xref:azure.core.paging.ItemPaged>[<xref:azure.ai.formrecognizer.OperationSummary>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError