Esta página se ha traducido con Cloud Translation API.

Gestionar operaciones de larga duración

Los métodos de procesamiento por lotes devuelven operaciones de larga duración porque tardan más en completarse de lo que es apropiado para una respuesta de API. De esta forma, el hilo de llamada no se mantiene abierto mientras se procesan muchos documentos. La API Document AI crea un LRO cada vez que llamas a projects.locations.processors.batchProcess a través de la API o de las bibliotecas de cliente. La LRO monitoriza el estado del trabajo de procesamiento.

Puedes usar los métodos de operaciones que proporciona la API de Document AI para comprobar el estado de las operaciones de larga duración. También puedes listar, consultar o cancelar operaciones LRO. Las bibliotecas de cliente llaman al método asíncrono internamente, lo que habilita la retrollamada. (En Python, await está habilitado). También incluyen un parámetro de tiempo de espera. En el LRO principal devuelto por .batchProcess, se crea un LRO para cada documento (porque los límites de recuento de páginas por lote son mucho más altos que la llamada process síncrona y pueden tardar mucho tiempo en procesarse). Cuando finaliza la LRO principal, se proporciona el estado detallado de cada LRO de documento.

Las operaciones de larga duración se gestionan a nivel de Google Cloud proyecto y ubicación. Cuando hagas una solicitud a la API, incluye el Google Cloud proyecto y la ubicación en la que se está ejecutando la operación de larga duración.

El registro de una operación de larga duración se conserva durante aproximadamente 30 días después de que finalice, lo que significa que no puedes ver ni enumerar una operación de larga duración después de ese periodo.

Obtener detalles sobre una operación de larga duración

En los siguientes ejemplos se muestra cómo obtener detalles de una operación LRO.

REST

Para obtener el estado de una operación de larga duración y ver sus detalles, llama al método projects.locations.operations.get.

Supongamos que recibes la siguiente respuesta después de llamar a projects.locations.processors.batchProcess:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID"
}

El valor name de la respuesta muestra que la API Document AI ha creado un LRO llamado projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID.

También puedes obtener el nombre de la LRO enumerando las operaciones de larga duración.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

PROJECT_ID: tu ID de proyecto Google Cloud .
LOCATION: la ubicación en la que se está ejecutando la operación de larga duración. Por ejemplo:
- us - Estados Unidos
- eu - Unión Europea
OPERATION_ID: el ID de tu operación. El ID es el último elemento del nombre de tu operación. Por ejemplo:
- Nombre de la operación: projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
- ID de operación: bc4e1d412863e626

Método HTTP y URL:

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

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

PowerShell

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

$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/operations/OPERATION_ID" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
    "state": "SUCCEEDED",
    "stateMessage": "Processed 1 document(s) successfully",
    "createTime": "TIMESTAMP",
    "updateTime": "TIMESTAMP",
    "individualProcessStatuses": [
      {
        "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",
        "status": {},
        "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",
        "humanReviewStatus": {
          "state": "ERROR",
          "stateMessage": "Sharded document protos are not supported for human review."
        }
      }
    ]
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"
  }
}

Go

Para obtener más información, consulta la documentación de referencia de la API Go de Document AI.

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.


package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	longrunningpb "cloud.google.com/go/longrunning/autogen/longrunningpb"
)

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 := &longrunningpb.GetOperationRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/longrunning/autogen/longrunningpb#GetOperationRequest.
	}
	resp, err := c.GetOperation(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.


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

# TODO(developer): Uncomment these variables before running the sample.
# location = "YOUR_PROCESSOR_LOCATION"  # Format is "us" or "eu"
# operation_name = "YOUR_OPERATION_NAME"  # Format is "projects/{project_id}/locations/{location}/operations/{operation_id}"


def get_operation_sample(location: str, operation_name: 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)

    request = GetOperationRequest(name=operation_name)

    # Make GetOperation request
    operation = client.get_operation(request=request)
    # Print the Operation Information
    print(operation)

Listar operaciones de larga duración

En los siguientes ejemplos se muestra cómo enumerar los LROs de un Google Cloud proyecto y una ubicación.

REST

Para obtener una lista de las operaciones LRO de un proyecto y una ubicación, llama al método projects.locations.operations.list. Google Cloud

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

PROJECT_ID: tu ID de proyecto Google Cloud .
LOCATION: la ubicación en la que se están ejecutando una o varias operaciones de larga duración. Por ejemplo:
- us - Estados Unidos
- eu - Unión Europea
FILTER: (obligatorio) consulta de LROs que se van a devolver. Opciones:
- TYPE: (obligatorio) Tipo de LRO que se va a enumerar. Opciones:

Método HTTP y URL:

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE"

PowerShell

Ejecuta el comando siguiente:

$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/operations?filter=TYPE=TYPE" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "operations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
        "state": "SUCCEEDED",
        "stateMessage": "Processed 1 document(s) successfully",
        "createTime": "TIMESTAMP",
        "updateTime": "TIMESTAMP",
        "individualProcessStatuses": [
          {
            "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",
            "status": {},
            "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",
            "humanReviewStatus": {
              "state": "ERROR",
              "stateMessage": "Sharded document protos are not supported for human review."
            }
          }
        ]
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"
      }
    },
    ...
  ]
}

Go

Para obtener más información, consulta la documentación de referencia de la API Go de Document AI.


package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	longrunningpb "cloud.google.com/go/longrunning/autogen/longrunningpb"
	"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 := &longrunningpb.ListOperationsRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/longrunning/autogen/longrunningpb#ListOperationsRequest.
	}
	it := c.ListOperations(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			// TODO: Handle error.
		}
		// TODO: Use resp.
		_ = resp

		// If you need to access the underlying RPC response,
		// you can do so by casting the `Response` as below.
		// Otherwise, remove this line. Only populated after
		// first call to Next(). Not safe for concurrent access.
		_ = it.Response.(*longrunningpb.ListOperationsResponse)
	}
}

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.


from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore
from google.longrunning.operations_pb2 import ListOperationsRequest  # 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"

# Create filter in https://google.aip.dev/160 syntax
# For full options, refer to:
# https://cloud.google.com/document-ai/docs/long-running-operations#listing_long-running_operations
# operations_filter = 'YOUR_FILTER'

# Example:
# operations_filter = "TYPE=BATCH_PROCESS_DOCUMENTS AND STATE=RUNNING"


def list_operations_sample(
    project_id: str, location: str, operations_filter: 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)

    # Format: `projects/{project_id}/locations/{location}`
    name = client.common_location_path(project=project_id, location=location)
    request = ListOperationsRequest(
        name=f"{name}/operations",
        filter=operations_filter,
    )

    # Make ListOperations request
    operations = client.list_operations(request=request)

    # Print the Operation Information
    print(operations)

Sondear una operación de larga duración

En los siguientes ejemplos se muestra cómo sondear el estado de una LRO.

REST

Para sondear un LRO, llama repetidamente al método projects.locations.operations.get hasta que finalice la operación. Usa un tiempo de espera entre cada solicitud de sondeo, como 10 segundos.

Antes de usar cualquiera de los datos de solicitud que se indican a continuación, haz los siguientes cambios:

PROJECT_ID: tu ID de proyecto Google Cloud
LOCATION: la ubicación en la que se está ejecutando la operación de larga duración
OPERATION_ID: el identificador del LRO

Método HTTP y URL:

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando para sondear el estado de un LRO cada 10 segundos:

while true; \
    do curl -X GET \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"; \
    sleep 10; \
    done

Deberías recibir una respuesta JSON cada 10 segundos. Mientras la operación esté en curso, la respuesta contendrá "state": "RUNNING". Cuando termine la operación, la respuesta contendrá "state": "SUCCEEDED" y "done": true.

Respuesta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
    "state": "RUNNING",
    "createTime": "TIMESTAMP",
    "updateTime": "TIMESTAMP"
  }
}
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
    "state": "RUNNING",
    "createTime": "TIMESTAMP",
    "updateTime": "TIMESTAMP"
  }
}
...
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
    "state": "SUCCEEDED",
    "stateMessage": "Processed 1 document(s) successfully",
    "createTime": "TIMESTAMP",
    "updateTime": "TIMESTAMP",
    "individualProcessStatuses": [
      {
        "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",
        "status": {},
        "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",
        "humanReviewStatus": {
          "state": "ERROR",
          "stateMessage": "Sharded document protos are not supported for human review."
        }
      }
    ]
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"
  }
}

PowerShell

Ejecuta el siguiente comando para sondear el estado de un LRO cada diez segundos:

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

Do {
  Invoke-WebRequest `
    -Method Get `
    -Headers $headers `
    -Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content
sleep 10
}

while ($true)

Respuesta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
    "state": "RUNNING",
    "createTime": "TIMESTAMP",
    "updateTime": "TIMESTAMP"
  }
}
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
    "state": "RUNNING",
    "createTime": "TIMESTAMP",
    "updateTime": "TIMESTAMP"
  }
}
...
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",
    "state": "SUCCEEDED",
    "stateMessage": "Processed 1 document(s) successfully",
    "createTime": "TIMESTAMP",
    "updateTime": "TIMESTAMP",
    "individualProcessStatuses": [
      {
        "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",
        "status": {},
        "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",
        "humanReviewStatus": {
          "state": "ERROR",
          "stateMessage": "Sharded document protos are not supported for human review."
        }
      }
    ]
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"
  }
}

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.


from time import sleep

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

# TODO(developer): Uncomment these variables before running the sample.
# location = "YOUR_PROCESSOR_LOCATION"  # Format is "us" or "eu"
# operation_name = "YOUR_OPERATION_NAME"  # Format is "projects/{project_id}/locations/{location}/operations/{operation_id}"


def poll_operation_sample(location: str, operation_name: 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)

    request = GetOperationRequest(name=operation_name)

    while True:
        # Make GetOperation request
        operation = client.get_operation(request=request)
        # Print the Operation Information
        print(operation)

        # Stop polling when Operation is no longer running
        if operation.done:
            break

        # Wait 10 seconds before polling again
        sleep(10)

Cancelar una operación de larga duración

En los siguientes ejemplos se muestra cómo cancelar una LRO mientras se está ejecutando.

REST

Para cancelar una operación de larga duración, llama al método projects.locations.operations.cancel.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

PROJECT_ID: tu ID de proyecto Google Cloud .
LOCATION: la ubicación en la que se está ejecutando la operación de larga duración. Por ejemplo:
- us - Estados Unidos
- eu - Unión Europea
OPERATION_ID: el ID de tu operación. El ID es el último elemento del nombre de tu operación. Por ejemplo:
- Nombre de la operación: projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
- ID de operación: bc4e1d412863e626

Método HTTP y URL:

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

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/operations/OPERATION_ID:cancel"

PowerShell

Ejecuta el comando siguiente:

$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/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{}

Si intentas cancelar una operación que ya se ha completado, deberías recibir el siguiente mensaje de error:

  "error": {
      "code": 400,
      "message": "Operation has completed and cannot be cancelled: 'PROJECT_ID/locations/LOCATION/operations/OPERATION_ID'.",
      "status": "FAILED_PRECONDITION"
  }

Go

Para obtener más información, consulta la documentación de referencia de la API Go de Document AI.


package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	longrunningpb "cloud.google.com/go/longrunning/autogen/longrunningpb"
)

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 := &longrunningpb.CancelOperationRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/longrunning/autogen/longrunningpb#CancelOperationRequest.
	}
	err = c.CancelOperation(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
}

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.


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

# TODO(developer): Uncomment these variables before running the sample.
# location = "YOUR_PROCESSOR_LOCATION"  # Format is "us" or "eu"
# operation_name = "YOUR_OPERATION_NAME"  # Format is "projects/{project_id}/locations/{location}/operations/{operation_id}"


def cancel_operation_sample(location: str, operation_name: 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)

    request = CancelOperationRequest(name=operation_name)

    # Make CancelOperation request
    client.cancel_operation(request=request)
    print(f"Operation {operation_name} cancelled")

Gestionar respuestas

Metadatos personalizados

Gestionar operaciones de larga duración Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Obtener detalles sobre una operación de larga duración

REST

curl

PowerShell

Go

Python

Listar operaciones de larga duración

REST

curl

PowerShell

Go

Python

Sondear una operación de larga duración

REST

curl

Respuesta

PowerShell

Respuesta

Python

Cancelar una operación de larga duración

REST

curl

PowerShell

Go

Python

Gestionar operaciones de larga duración