Stay organized with collections Save and categorize content based on your preferences.

Managing processor versions

A processor can have multiple versions, for example, a Stable version for production workloads and a Release Candidate (RC) that implements the latest features. By switching between different versions, you can choose which implementation is used to process documents.

Google releases new versions for a variety of reasons, for example, to improve the processor accuracy, add support for new forms, such as annual updates to tax forms, and/or support additional form fields.

This page describes how processors are versioned, and how to view and select a particular version.

Processor versions

Each version is identified by a Version ID, for example pretrained-TYPE-vX.X-YYYY-MM-DD. pretrained indicates that the model is trained by Google and TYPE indicates the processor type, for example invoice. Each processor version is categorized as either Stable or Release Candidate (RC).

Stable channel

  • Stable versions are production-quality and ready for use. Google will prioritize stability of the processor behaviour, but will still include security or other critical fixes
  • Google will support each Stable version for a minimum of 9 months (270 days)
  • Google may support up to 4 Stable versions at a time

Release Candidate (RC) channel

  • Release Candidates are experimental
  • Non-production quality, no stability guaranteed
  • Upgraded regularly
  • May support additional functionality. For example, parsers may detect additional fields, and splitters may detect additional document types.

Select a processor version

There are three ways to specify which processor version to use for online and batch processing:

  • If you do not specify a version, the processor's default is used.

    • Example: projects/my-proj/locations/us/processors/my-processor:process
  • If you specify a version, then that specific version is used. If the specific version does not exist, the request fails with an error.

    • Example: projects/my-proj/locations/us/processors/my-processor/processorVersions/pretrained-invoice-v1.2-2022-02-18:process
  • If you specify a channel then the latest version in that channel is used. (Options: stable, rc)

    • Example: projects/my-proj/locations/us/processors/my-processor/processorVersions/stable:process

View available versions

Web UI

  1. In the Google Cloud console, in the Document AI section, go to the Processors page.

    Go to Processors

  2. From the list of processors, click on the name of the processor that you want to view details for.

  3. Select the Manage Versions tab, which will display all of the available processor versions.

REST

This sample shows how to list the available processor versions for your processor using the processorVersions.list method.

Before using any of the request data, make the following replacements:

  • LOCATION: your processor's location, for example:
    • us - United States
    • eu - European Union
  • PROJECT_ID: Your Google Cloud project ID.
  • PROCESSOR_ID: the ID of your custom processor.

HTTP method and URL:

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions" | Select-Object -Expand Content

The response contains a list of ProcessorVersions, which contains information about each processor version such as its name, state, and other details.

{
  "processorVersions": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/pretrained-ocr-v1.1-2022-09-12",
      "displayName": "Google Release Candidate",
      "state": "DEPLOYED",
      "createTime": "2022-09-13T23:39:12.156648Z",
      "googleManaged": true
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/pretrained-ocr-v1.0-2020-09-23",
      "displayName": "Google Stable",
      "state": "DEPLOYED",
      "createTime": "2022-09-12T23:35:09.829557Z",
      "googleManaged": true,
      "deprecationInfo": {
        "deprecationTime": "1970-01-01T00:00:00Z"
      }
    }
  ]
}

Python

For more information, see the Document AI Python API reference documentation.


from google.api_core.client_options import ClientOptions
from google.cloud import documentai

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample


def list_processor_versions_sample(project_id: str, location: str, processor_id: str):
    # You must set the api_endpoint if you use a location other than 'us'.
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor
    # e.g.: projects/project_id/locations/location/processors/processor_id
    parent = client.processor_path(project_id, location, processor_id)

    # Make ListProcessorVersions request
    processor_versions = client.list_processor_versions(parent=parent)

    # Print the processor version information
    for processor_version in processor_versions:
        processor_version_id = client.parse_processor_version_path(
            processor_version.name
        )["processor_version"]

        print(f"Processor Version: {processor_version_id}")
        print(f"Display Name: {processor_version.display_name}")
        print(processor_version.state)
        print("")

View details about a version

Web UI

  1. In the Google Cloud console, in the Document AI section, go to the Processors page.

    Go to Processors

  2. From the list of processors, click on the name of the processor that you want to view details for.

  3. Select the Manage Versions tab, which will display all of the available processor versions and their details.

REST

This sample shows how to get details about a processor version for your processor using the processorVersions.get method.

Before using any of the request data, make the following replacements:

  • LOCATION: your processor's location, for example:
    • us - United States
    • eu - European Union
  • PROJECT_ID: Your Google Cloud project ID.
  • PROCESSOR_ID: the ID of your custom processor.
  • PROCESSOR_VERSION: the processor version identifier. Refer to Select a processor version for more information. For example:
    • pretrained-TYPE-vX.X-YYYY-MM-DD
    • stable
    • rc

HTTP method and URL:

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION" | Select-Object -Expand Content

The response is a ProcessorVersion, which contains information about the processor version such as its name, state, and other details.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/pretrained-ocr-v1.1-2022-09-12",
  "displayName": "Google Release Candidate",
  "state": "DEPLOYED",
  "createTime": "2022-09-13T23:39:12.156648Z",
  "googleManaged": true
}

Python

For more information, see the Document AI Python API reference documentation.


from google.api_core.client_options import ClientOptions
from google.cloud import documentai

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def get_processor_version_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
):
    # You must set the api_endpoint if you use a location other than 'us'.
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g.: projects/project_id/locations/location/processors/processor_id/processorVersions/processor_version_id
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    # Make GetProcessorVersion request
    processor_version = client.get_processor_version(name=name)

    # Print the processor version information
    print(f"Processor Version: {processor_version_id}")
    print(f"Display Name: {processor_version.display_name}")
    print(processor_version.state)

Change the default version

A processor's default version specifies the version that is used to process documents when you don't specify a specific version. When you create a processor, the initial default version is the latest version in the stable channel.

If you change the default version, incoming requests are processed using the newly selected version. If you change the default version while the processor is in the middle of a request, the request will continue to use the previously selected version.

To change the default version:

Web UI

  1. In the Google Cloud console, in the Document AI section, go to the Processors page.

    Go to the Processors page

  2. From the list of processors, click on the name of the processor that you want to view details for.

  3. In the processor's Manage Versions tab, in the Default version dropdown menu, choose a version of the processor that you want to use as the default version.

REST

This sample shows how to set the default processor version for your processor using the processors.setDefaultProcessorVersion method.

Before using any of the request data, make the following replacements:

  • LOCATION: your processor's location, for example:
    • us - United States
    • eu - European Union
  • PROJECT_ID: Your Google Cloud project ID.
  • PROCESSOR_ID: the ID of your custom processor.
  • PROCESSOR_VERSION: the processor version identifier. Refer to Select a processor version for more information. For example:
    • pretrained-TYPE-vX.X-YYYY-MM-DD
    • stable
    • rc

HTTP method and URL:

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:setDefaultProcessorVersion

Request JSON body:

{
  "defaultProcessorVersion": "PROCESSOR_VERSION"
}

To send your request, choose one of these options:

curl

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:setDefaultProcessorVersion"

PowerShell

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:setDefaultProcessorVersion" | Select-Object -Expand Content

The response is a long running operation. To poll the long-running operation, call operations.get

The SetDefaultProcessorVersionMetadata in the response indicates the state of the operation.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.SetDefaultProcessorVersionMetadata",
    "commonMetadata": {
      "state": "SUCCEEDED",
      "createTime": "2022-03-02T22:52:49.957096Z",
      "updateTime": "2022-03-02T22:52:50.175976Z",
      "resource": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.SetDefaultProcessorVersionResponse"
  }
}

Python

For more information, see the Document AI Python API reference documentation.


from google.api_core.client_options import ClientOptions
from google.api_core.exceptions import NotFound
from google.cloud import documentai

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def set_default_processor_version_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
):
    # You must set the api_endpoint if you use a location other than 'us'.
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor
    # e.g.: projects/project_id/locations/location/processors/processor_id
    processor = client.processor_path(project_id, location, processor_id)

    # The full resource name of the processor version
    # e.g.: projects/project_id/locations/location/processors/processor_id/processorVersions/processor_version_id
    processor_version = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    request = documentai.SetDefaultProcessorVersionRequest(
        processor=processor, default_processor_version=processor_version
    )

    # Make SetDefaultProcessorVersion request
    try:
        operation = client.set_default_processor_version(request)
        # Print operation details
        print(operation.operation.name)
        # Wait for operation to complete
        operation.result()
    except NotFound as e:
        print(e.message)

Deploy a processor version

After creating a new processor version with Document AI Workbench, you will need to deploy it before you can process documents with this version.

Web UI

  1. In the Google Cloud console, in the Document AI section, go to the Processors page.

    Go to the Processors page

  2. From the list of processors, click on the name of the processor that you want to view details for.

  3. In the processor's Manage Versions tab, select the checkbox next to the processor version you want to deploy.

  4. Click on the Deploy button, then click Deploy on the pop-up window. This will take a few minutes to complete.

REST

This sample shows how to deploy a processor version for your processor using the processorVersions.deploy method.

Before using any of the request data, make the following replacements:

  • LOCATION: your processor's location, for example:
    • us - United States
    • eu - European Union
  • PROJECT_ID: Your Google Cloud project ID.
  • PROCESSOR_ID: the ID of your custom processor.
  • PROCESSOR_VERSION: the processor version identifier.

HTTP method and URL:

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:deploy

To send your request, choose one of these options:

curl

Execute the following command:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:deploy"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:deploy" | Select-Object -Expand Content

The response is a long running operation. To poll the long-running operation, call operations.get

The DeployProcessorVersionMetadata in the response indicates the state of the operation.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.DeployProcessorVersionMetadata",
    "commonMetadata": {
      "state": "SUCCEEDED",
      "createTime": "2022-08-29T16:27:00.195539Z",
      "updateTime": "2022-08-29T16:32:01.963962Z",
      "resource": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.DeployProcessorVersionResponse"
  }
}

Python

For more information, see the Document AI Python API reference documentation.


from google.api_core.client_options import ClientOptions
from google.api_core.exceptions import FailedPrecondition
from google.cloud import documentai

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID'
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def deploy_processor_version_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
):
    # You must set the api_endpoint if you use a location other than 'us'.
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g.: projects/project_id/locations/location/processors/processor_id/processorVersions/processor_version_id
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    # Make DeployProcessorVersion request
    try:
        operation = client.deploy_processor_version(name=name)
        # Print operation details
        print(operation.operation.name)
        # Wait for operation to complete
        operation.result()
    # Deploy request will fail if the
    # processor version is already deployed
    except FailedPrecondition as e:
        print(e.message)

Undeploy a processor version

After creating a new processor version with Document AI Workbench and deploying it, you can undeploy it if you do not want the processor version to be able to handle processing requests.

Web UI

  1. In the Google Cloud console, in the Document AI section, go to the Processors page.

    Go to the Processors page

  2. From the list of processors, click on the name of the processor that you want to view details for.

  3. In the processor's Manage Versions tab, select the checkbox next to the processor version you want to undeploy.

  4. Click on the Undeploy button, then click Undeploy on the pop-up window. This will take a few minutes to complete.

REST

This sample shows how to undeploy a processor version for your processor using the processorVersions.undeploy method.

Before using any of the request data, make the following replacements:

  • LOCATION: your processor's location, for example:
    • us - United States
    • eu - European Union
  • PROJECT_ID: Your Google Cloud project ID.
  • PROCESSOR_ID: the ID of your custom processor.
  • PROCESSOR_VERSION: the processor version identifier.

HTTP method and URL:

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:undeploy

To send your request, choose one of these options:

curl

Execute the following command:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:undeploy"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:undeploy" | Select-Object -Expand Content

The response is a long running operation. To poll the long-running operation, call operations.get

The UndeployProcessorVersionMetadata in the response indicates the state of the operation.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.UndeployProcessorVersionMetadata",
    "commonMetadata": {
      "state": "SUCCEEDED",
      "createTime": "2022-08-29T16:27:00.195539Z",
      "updateTime": "2022-08-29T16:32:01.963962Z",
      "resource": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.UndeployProcessorVersionResponse"
  }
}

Python

For more information, see the Document AI Python API reference documentation.


from google.api_core.client_options import ClientOptions
from google.api_core.exceptions import FailedPrecondition
from google.api_core.exceptions import InvalidArgument
from google.cloud import documentai

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def undeploy_processor_version_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
):
    # You must set the api_endpoint if you use a location other than 'us'.
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g.: projects/project_id/locations/location/processors/processor_id/processorVersions/processor_version_id
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    # Make UndeployProcessorVersion request
    try:
        operation = client.undeploy_processor_version(name=name)
        # Print operation details
        print(operation.operation.name)
        # Wait for operation to complete
        operation.result()
    # Undeploy request will fail if the
    # processor version is already undeployed
    # or if a request is made on a pretrained processor version
    except (FailedPrecondition, InvalidArgument) as e:
        print(e.message)

Delete a processor version

After creating a new processor version with Document AI Workbench, you can delete it if you have no further use for the processor version.

Web UI

  1. In the Google Cloud console, in the Document AI section, go to the Processors page.

    Go to the Processors page

  2. From the list of processors, click on the name of the processor that you want to view details for.

  3. In the processor's Manage Versions tab, click on the action menu next to the processor version you want to delete.

  4. Click on the Delete button, then click Delete on the pop-up window.

REST

This sample shows how to delete a processor version for your processor using the processorVersions.delete method.

Before using any of the request data, make the following replacements:

  • LOCATION: your processor's location, for example:
    • us - United States
    • eu - European Union
  • PROJECT_ID: Your Google Cloud project ID.
  • PROCESSOR_ID: the ID of your custom processor.
  • PROCESSOR_VERSION: the processor version identifier.

HTTP method and URL:

DELETE https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION

To send your request, choose one of these options:

curl

Execute the following command:

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION" | Select-Object -Expand Content

The response is a long running operation. To poll the long-running operation, call operations.get

The DeleteProcessorVersionMetadata in the response indicates the state of the operation.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.DeleteProcessorVersionMetadata",
    "commonMetadata": {
      "state": "SUCCEEDED",
      "createTime": "2022-08-29T16:27:00.195539Z",
      "updateTime": "2022-08-29T16:32:01.963962Z",
      "resource": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Python

For more information, see the Document AI Python API reference documentation.


from google.api_core.client_options import ClientOptions
from google.api_core.exceptions import FailedPrecondition
from google.api_core.exceptions import InvalidArgument
from google.cloud import documentai

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def delete_processor_version_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
):
    # You must set the api_endpoint if you use a location other than 'us'.
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g.: projects/project_id/locations/location/processors/processor_id/processorVersions/processor_version_id
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    # Make DeleteProcessorVersion request
    try:
        operation = client.delete_processor_version(name=name)
        # Print operation details
        print(operation.operation.name)
        # Wait for operation to complete
        operation.result()
    # Delete request will fail if the
    # processor version doesn't exist
    # or if a request is made on a pretrained processor version
    # or the default processor version
    except (FailedPrecondition, InvalidArgument) as e:
        print(e.message)

Import a processor version

After creating a new processor with Document AI Workbench, you can import a processor version from the same or different project.

The destination project is where you click the import button in the UI or call the import processor version.

The source project is where the source processor version lives.

The source/destination processors must meet the following requirements to import:

  • Processor types must match.
    • Examples: CUSTOM_EXTRACTION_PROCESSOR or INVOICE_PROCESSOR
  • Processor schemas must not conflict.
  • Destination processor can have existing datasets/versions.
  • Destination processor must be in ENABLED state.
  • Source processor version must be in one of the following states:
    • DEPLOYED
    • DEPLOYING
    • UNDEPLOYED
    • UNDEPLOYING

You must grant the DocumentAI Core Service Agent of the destination project Document AI Editor permission on the source project to avoid permission denied error.

Complete the following steps to set up permission before importing a processor version:

Web UI

  1. Look up DocumentAI Core Service Agent and fill in your destination project number. The DocumentAI Core Service Agent is formatted like an email address. For example: service-123@gcp-sa-prod-dai-core.iam.gserviceaccount.com

  2. Open the IAM page in the Google Cloud console.

    Open the IAM page

  3. Select your source project.

  4. Click grant access.

  5. Add the destination project's DocumentAI Core Service Agent as a new principal, and assign Document AI Editor role.

gcloud

Use the following gcloud command to grant the necessary permissions:

gcloud projects add-iam-policy-binding SOURCE_PROJECT \
    --member=serviceAccount:service-DESTINATION_PROJECT NUMBER@gcp-sa-prod-dai-core.iam.gserviceaccount.com \
    --role=roles/documentai.editor

Provide the following values:

  • SOURCE_PROJECT: The source project number or project id.
  • DESTINATION_PROJECT NUMBER: The destination project number.

After updating the permissions, use the following steps to import a processor version:

Web UI

  1. In the Google Cloud console, in the Document AI section, go to the Processors page.

    Go to the Processors page

  2. From the list of processors, click on the name of the processor that you want to import a processor version to as a destination processor.

  3. Go to the Manage Versions tab, and click on the IMPORT button.

  4. Choose the project, the processor, and the processor version as the source processor version in the window.

  5. Click IMPORT button in the window, and the import operation will start.