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

Note: Previously, some processor versions were named Google default or Google Default Next and versioned pretrained or pretrained-next.

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

Note: Some processors have only one 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.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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"
      }
    }
  ]
}

C#

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

using Google.Api.Gax;
using Google.Cloud.DocumentAI.V1;
using System;

public sealed partial class GeneratedDocumentProcessorServiceClientSnippets
{
    /// <summary>Snippet for ListProcessorVersions</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void ListProcessorVersionsRequestObject()
    {
        // Create client
        DocumentProcessorServiceClient documentProcessorServiceClient = DocumentProcessorServiceClient.Create();
        // Initialize request argument(s)
        ListProcessorVersionsRequest request = new ListProcessorVersionsRequest
        {
            ParentAsProcessorName = ProcessorName.FromProjectLocationProcessor("[PROJECT]", "[LOCATION]", "[PROCESSOR]"),
        };
        // Make the request
        PagedEnumerable<ListProcessorVersionsResponse, ProcessorVersion> response = documentProcessorServiceClient.ListProcessorVersions(request);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (ProcessorVersion item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (ListProcessorVersionsResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (ProcessorVersion item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<ProcessorVersion> singlePage = response.ReadPage(pageSize);
        // Do something with the page of items
        Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
        foreach (ProcessorVersion item in singlePage)
        {
            // Do something with each item
            Console.WriteLine(item);
        }
        // Store the pageToken, for when the next page is required.
        string nextPageToken = singlePage.NextPageToken;
    }
}

Go

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	documentaipb "cloud.google.com/go/documentai/apiv1/documentaipb"
	"google.golang.org/api/iterator"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := documentai.NewDocumentProcessorClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &documentaipb.ListProcessorVersionsRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/documentai/apiv1/documentaipb#ListProcessorVersionsRequest.
	}
	it := c.ListProcessorVersions(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			// TODO: Handle error.
		}
		// TODO: Use resp.
		_ = resp
	}
}

Java

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.ListProcessorVersionsRequest;
import com.google.cloud.documentai.v1.ProcessorName;
import com.google.cloud.documentai.v1.ProcessorVersion;

public class SyncListProcessorVersions {

  public static void main(String[] args) throws Exception {
    syncListProcessorVersions();
  }

  public static void syncListProcessorVersions() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentProcessorServiceClient documentProcessorServiceClient =
        DocumentProcessorServiceClient.create()) {
      ListProcessorVersionsRequest request =
          ListProcessorVersionsRequest.newBuilder()
              .setParent(ProcessorName.of("[PROJECT]", "[LOCATION]", "[PROCESSOR]").toString())
              .setPageSize(883849137)
              .setPageToken("pageToken873572522")
              .build();
      for (ProcessorVersion element :
          documentProcessorServiceClient.listProcessorVersions(request).iterateAll()) {
        // doThingsWith(element);
      }
    }
  }
}

Python

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# 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
) -> None:
    # 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("")

Ruby

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

require "google/cloud/document_ai/v1"

##
# Snippet for the list_processor_versions call in the DocumentProcessorService service
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client#list_processor_versions.
# It may require modification in order to execute successfully.
#
def list_processor_versions
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DocumentAI::V1::ListProcessorVersionsRequest.new

  # Call the list_processor_versions method.
  result = client.list_processor_versions request

  # The returned object is of type Gapic::PagedEnumerable. You can iterate
  # over elements, and API calls will be issued to fetch pages as needed.
  result.each do |item|
    # Each element is of type ::Google::Cloud::DocumentAI::V1::ProcessorVersion.
    p item
  end
end

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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
}

C#

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

using Google.Cloud.DocumentAI.V1;

public sealed partial class GeneratedDocumentProcessorServiceClientSnippets
{
    /// <summary>Snippet for GetProcessorVersion</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void GetProcessorVersionRequestObject()
    {
        // Create client
        DocumentProcessorServiceClient documentProcessorServiceClient = DocumentProcessorServiceClient.Create();
        // Initialize request argument(s)
        GetProcessorVersionRequest request = new GetProcessorVersionRequest
        {
            ProcessorVersionName = ProcessorVersionName.FromProjectLocationProcessorProcessorVersion("[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]"),
        };
        // Make the request
        ProcessorVersion response = documentProcessorServiceClient.GetProcessorVersion(request);
    }
}

Go

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	documentaipb "cloud.google.com/go/documentai/apiv1/documentaipb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := documentai.NewDocumentProcessorClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &documentaipb.GetProcessorVersionRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/documentai/apiv1/documentaipb#GetProcessorVersionRequest.
	}
	resp, err := c.GetProcessorVersion(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.GetProcessorVersionRequest;
import com.google.cloud.documentai.v1.ProcessorVersion;
import com.google.cloud.documentai.v1.ProcessorVersionName;

public class SyncGetProcessorVersion {

  public static void main(String[] args) throws Exception {
    syncGetProcessorVersion();
  }

  public static void syncGetProcessorVersion() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentProcessorServiceClient documentProcessorServiceClient =
        DocumentProcessorServiceClient.create()) {
      GetProcessorVersionRequest request =
          GetProcessorVersionRequest.newBuilder()
              .setName(
                  ProcessorVersionName.of(
                          "[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]")
                      .toString())
              .build();
      ProcessorVersion response = documentProcessorServiceClient.getProcessorVersion(request);
    }
  }
}

Python

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# 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
) -> None:
    # 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)

Ruby

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

require "google/cloud/document_ai/v1"

##
# Snippet for the get_processor_version call in the DocumentProcessorService service
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client#get_processor_version.
# It may require modification in order to execute successfully.
#
def get_processor_version
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DocumentAI::V1::GetProcessorVersionRequest.new

  # Call the get_processor_version method.
  result = client.get_processor_version request

  # The returned object is of type Google::Cloud::DocumentAI::V1::ProcessorVersion.
  p result
end

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named 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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named 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"
  }
}

C#

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

using Google.Cloud.DocumentAI.V1;
using Google.LongRunning;

public sealed partial class GeneratedDocumentProcessorServiceClientSnippets
{
    /// <summary>Snippet for SetDefaultProcessorVersion</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void SetDefaultProcessorVersionRequestObject()
    {
        // Create client
        DocumentProcessorServiceClient documentProcessorServiceClient = DocumentProcessorServiceClient.Create();
        // Initialize request argument(s)
        SetDefaultProcessorVersionRequest request = new SetDefaultProcessorVersionRequest
        {
            ProcessorAsProcessorName = ProcessorName.FromProjectLocationProcessor("[PROJECT]", "[LOCATION]", "[PROCESSOR]"),
            DefaultProcessorVersionAsProcessorVersionName = ProcessorVersionName.FromProjectLocationProcessorProcessorVersion("[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]"),
        };
        // Make the request
        Operation<SetDefaultProcessorVersionResponse, SetDefaultProcessorVersionMetadata> response = documentProcessorServiceClient.SetDefaultProcessorVersion(request);

        // Poll until the returned long-running operation is complete
        Operation<SetDefaultProcessorVersionResponse, SetDefaultProcessorVersionMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        SetDefaultProcessorVersionResponse result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<SetDefaultProcessorVersionResponse, SetDefaultProcessorVersionMetadata> retrievedResponse = documentProcessorServiceClient.PollOnceSetDefaultProcessorVersion(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            SetDefaultProcessorVersionResponse retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	documentaipb "cloud.google.com/go/documentai/apiv1/documentaipb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := documentai.NewDocumentProcessorClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &documentaipb.SetDefaultProcessorVersionRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/documentai/apiv1/documentaipb#SetDefaultProcessorVersionRequest.
	}
	op, err := c.SetDefaultProcessorVersion(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.ProcessorName;
import com.google.cloud.documentai.v1.ProcessorVersionName;
import com.google.cloud.documentai.v1.SetDefaultProcessorVersionRequest;
import com.google.cloud.documentai.v1.SetDefaultProcessorVersionResponse;

public class SyncSetDefaultProcessorVersion {

  public static void main(String[] args) throws Exception {
    syncSetDefaultProcessorVersion();
  }

  public static void syncSetDefaultProcessorVersion() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentProcessorServiceClient documentProcessorServiceClient =
        DocumentProcessorServiceClient.create()) {
      SetDefaultProcessorVersionRequest request =
          SetDefaultProcessorVersionRequest.newBuilder()
              .setProcessor(ProcessorName.of("[PROJECT]", "[LOCATION]", "[PROCESSOR]").toString())
              .setDefaultProcessorVersion(
                  ProcessorVersionName.of(
                          "[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]")
                      .toString())
              .build();
      SetDefaultProcessorVersionResponse response =
          documentProcessorServiceClient.setDefaultProcessorVersionAsync(request).get();
    }
  }
}

Python

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

from google.api_core.client_options import ClientOptions
from google.api_core.exceptions import NotFound
from google.cloud import documentai  # type: ignore

# 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
) -> None:
    # 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)

Ruby

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

require "google/cloud/document_ai/v1"

##
# Snippet for the set_default_processor_version call in the DocumentProcessorService service
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client#set_default_processor_version.
# It may require modification in order to execute successfully.
#
def set_default_processor_version
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DocumentAI::V1::SetDefaultProcessorVersionRequest.new

  # Call the set_default_processor_version method.
  result = client.set_default_processor_version request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

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.

Note: You cannot change the deployment status for pretrained processor versions or the current 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, 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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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"
  }
}

C#

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

using Google.Cloud.DocumentAI.V1;
using Google.LongRunning;

public sealed partial class GeneratedDocumentProcessorServiceClientSnippets
{
    /// <summary>Snippet for DeployProcessorVersion</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void DeployProcessorVersionRequestObject()
    {
        // Create client
        DocumentProcessorServiceClient documentProcessorServiceClient = DocumentProcessorServiceClient.Create();
        // Initialize request argument(s)
        DeployProcessorVersionRequest request = new DeployProcessorVersionRequest
        {
            ProcessorVersionName = ProcessorVersionName.FromProjectLocationProcessorProcessorVersion("[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]"),
        };
        // Make the request
        Operation<DeployProcessorVersionResponse, DeployProcessorVersionMetadata> response = documentProcessorServiceClient.DeployProcessorVersion(request);

        // Poll until the returned long-running operation is complete
        Operation<DeployProcessorVersionResponse, DeployProcessorVersionMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        DeployProcessorVersionResponse result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<DeployProcessorVersionResponse, DeployProcessorVersionMetadata> retrievedResponse = documentProcessorServiceClient.PollOnceDeployProcessorVersion(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            DeployProcessorVersionResponse retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	documentaipb "cloud.google.com/go/documentai/apiv1/documentaipb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := documentai.NewDocumentProcessorClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &documentaipb.DeployProcessorVersionRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/documentai/apiv1/documentaipb#DeployProcessorVersionRequest.
	}
	op, err := c.DeployProcessorVersion(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import com.google.cloud.documentai.v1.DeployProcessorVersionRequest;
import com.google.cloud.documentai.v1.DeployProcessorVersionResponse;
import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.ProcessorVersionName;

public class SyncDeployProcessorVersion {

  public static void main(String[] args) throws Exception {
    syncDeployProcessorVersion();
  }

  public static void syncDeployProcessorVersion() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentProcessorServiceClient documentProcessorServiceClient =
        DocumentProcessorServiceClient.create()) {
      DeployProcessorVersionRequest request =
          DeployProcessorVersionRequest.newBuilder()
              .setName(
                  ProcessorVersionName.of(
                          "[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]")
                      .toString())
              .build();
      DeployProcessorVersionResponse response =
          documentProcessorServiceClient.deployProcessorVersionAsync(request).get();
    }
  }
}

Python

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

from google.api_core.client_options import ClientOptions
from google.api_core.exceptions import FailedPrecondition
from google.cloud import documentai  # type: ignore

# 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
) -> None:
    # 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)

Ruby

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

require "google/cloud/document_ai/v1"

##
# Snippet for the deploy_processor_version call in the DocumentProcessorService service
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client#deploy_processor_version.
# It may require modification in order to execute successfully.
#
def deploy_processor_version
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DocumentAI::V1::DeployProcessorVersionRequest.new

  # Call the deploy_processor_version method.
  result = client.deploy_processor_version request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

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.

Note: You cannot change the deployment status for pretrained processor versions or the current 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, 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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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"
  }
}

C#

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

using Google.Cloud.DocumentAI.V1;
using Google.LongRunning;

public sealed partial class GeneratedDocumentProcessorServiceClientSnippets
{
    /// <summary>Snippet for UndeployProcessorVersion</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void UndeployProcessorVersionRequestObject()
    {
        // Create client
        DocumentProcessorServiceClient documentProcessorServiceClient = DocumentProcessorServiceClient.Create();
        // Initialize request argument(s)
        UndeployProcessorVersionRequest request = new UndeployProcessorVersionRequest
        {
            ProcessorVersionName = ProcessorVersionName.FromProjectLocationProcessorProcessorVersion("[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]"),
        };
        // Make the request
        Operation<UndeployProcessorVersionResponse, UndeployProcessorVersionMetadata> response = documentProcessorServiceClient.UndeployProcessorVersion(request);

        // Poll until the returned long-running operation is complete
        Operation<UndeployProcessorVersionResponse, UndeployProcessorVersionMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        UndeployProcessorVersionResponse result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<UndeployProcessorVersionResponse, UndeployProcessorVersionMetadata> retrievedResponse = documentProcessorServiceClient.PollOnceUndeployProcessorVersion(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            UndeployProcessorVersionResponse retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	documentaipb "cloud.google.com/go/documentai/apiv1/documentaipb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := documentai.NewDocumentProcessorClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &documentaipb.UndeployProcessorVersionRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/documentai/apiv1/documentaipb#UndeployProcessorVersionRequest.
	}
	op, err := c.UndeployProcessorVersion(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.ProcessorVersionName;
import com.google.cloud.documentai.v1.UndeployProcessorVersionRequest;
import com.google.cloud.documentai.v1.UndeployProcessorVersionResponse;

public class SyncUndeployProcessorVersion {

  public static void main(String[] args) throws Exception {
    syncUndeployProcessorVersion();
  }

  public static void syncUndeployProcessorVersion() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentProcessorServiceClient documentProcessorServiceClient =
        DocumentProcessorServiceClient.create()) {
      UndeployProcessorVersionRequest request =
          UndeployProcessorVersionRequest.newBuilder()
              .setName(
                  ProcessorVersionName.of(
                          "[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]")
                      .toString())
              .build();
      UndeployProcessorVersionResponse response =
          documentProcessorServiceClient.undeployProcessorVersionAsync(request).get();
    }
  }
}

Python

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

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  # type: ignore

# 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
) -> None:
    # 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)

Ruby

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

require "google/cloud/document_ai/v1"

##
# Snippet for the undeploy_processor_version call in the DocumentProcessorService service
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client#undeploy_processor_version.
# It may require modification in order to execute successfully.
#
def undeploy_processor_version
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DocumentAI::V1::UndeployProcessorVersionRequest.new

  # Call the undeploy_processor_version method.
  result = client.undeploy_processor_version request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

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.

Note: You cannot delete pretrained processor versions or the current 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, 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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

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"
  }
}

C#

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

using Google.Cloud.DocumentAI.V1;
using Google.LongRunning;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedDocumentProcessorServiceClientSnippets
{
    /// <summary>Snippet for DeleteProcessorVersion</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void DeleteProcessorVersionRequestObject()
    {
        // Create client
        DocumentProcessorServiceClient documentProcessorServiceClient = DocumentProcessorServiceClient.Create();
        // Initialize request argument(s)
        DeleteProcessorVersionRequest request = new DeleteProcessorVersionRequest
        {
            ProcessorVersionName = ProcessorVersionName.FromProjectLocationProcessorProcessorVersion("[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]"),
        };
        // Make the request
        Operation<Empty, DeleteProcessorVersionMetadata> response = documentProcessorServiceClient.DeleteProcessorVersion(request);

        // Poll until the returned long-running operation is complete
        Operation<Empty, DeleteProcessorVersionMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Empty result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Empty, DeleteProcessorVersionMetadata> retrievedResponse = documentProcessorServiceClient.PollOnceDeleteProcessorVersion(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Empty retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	documentaipb "cloud.google.com/go/documentai/apiv1/documentaipb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := documentai.NewDocumentProcessorClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &documentaipb.DeleteProcessorVersionRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/documentai/apiv1/documentaipb#DeleteProcessorVersionRequest.
	}
	op, err := c.DeleteProcessorVersion(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	err = op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
}

Java

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

import com.google.cloud.documentai.v1.DeleteProcessorVersionRequest;
import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.ProcessorVersionName;
import com.google.protobuf.Empty;

public class SyncDeleteProcessorVersion {

  public static void main(String[] args) throws Exception {
    syncDeleteProcessorVersion();
  }

  public static void syncDeleteProcessorVersion() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentProcessorServiceClient documentProcessorServiceClient =
        DocumentProcessorServiceClient.create()) {
      DeleteProcessorVersionRequest request =
          DeleteProcessorVersionRequest.newBuilder()
              .setName(
                  ProcessorVersionName.of(
                          "[PROJECT]", "[LOCATION]", "[PROCESSOR]", "[PROCESSOR_VERSION]")
                      .toString())
              .build();
      documentProcessorServiceClient.deleteProcessorVersionAsync(request).get();
    }
  }
}

Python

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

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  # type: ignore

# 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
) -> None:
    # 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)

Ruby

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

To authenticate to Document AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

View on GitHub Feedback

require "google/cloud/document_ai/v1"

##
# Snippet for the delete_processor_version call in the DocumentProcessorService service
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client#delete_processor_version.
# It may require modification in order to execute successfully.
#
def delete_processor_version
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DocumentAI::V1::DocumentProcessorService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DocumentAI::V1::DeleteProcessorVersionRequest.new

  # Call the delete_processor_version method.
  result = client.delete_processor_version request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

Import a processor version

After creating a new processor with Document AI Workbench, you can import a processor version from the same or a 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.

Note: This applies if importing processor versions within the same project or between separate projects.

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: [e-mail]

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 [e-mail] \
    --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.

REST

This sample shows you how to use the processorVersions.importProcessorVersion method to import a processor version.

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

• Destination Project
  • DESTINATION_PROJECT_ID: your destination Google Cloud project ID.
  • DESTINATION_LOCATION: your destination processor's location.
  • DESTINATION_PROCESSOR_ID: the ID of your destination processor.
• Source Project
  • SOURCE_PROJECT_ID: your source Google Cloud project ID.
  • SOURCE_LOCATION: the source processor's location.
  • SOURCE_PROCESSOR_ID: the ID of your source processor.
  • SOURCE_PROCESSOR_VERSION: the source processor version to import.

HTTP method and URL:

POST https://DESTINATION_LOCATION-documentai.googleapis.com/v1beta3/projects/DESTINATION_PROJECT_ID/locations/DESTINATION_LOCATION/processors/DESTINATION_PROCESSOR_ID/processorVersions:importProcessorVersion

Request JSON body:

{
  "processorVersionSource": "projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/processors/SOURCE_PROCESSOR_ID/processorVersions/SOURCE_PROCESSOR_VERSION"
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named 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://DESTINATION_LOCATION-documentai.googleapis.com/v1beta3/projects/DESTINATION_PROJECT_ID/locations/DESTINATION_LOCATION/processors/DESTINATION_PROCESSOR_ID/processorVersions:importProcessorVersion"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named 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://DESTINATION_LOCATION-documentai.googleapis.com/v1beta3/projects/DESTINATION_PROJECT_ID/locations/DESTINATION_LOCATION/processors/DESTINATION_PROCESSOR_ID/processorVersions:importProcessorVersion" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/DESTINATION_PROJECT_ID/locations/DESTINATION_LOCATION/operations/OPERATION_ID"
}