Supervisa las operaciones de larga duración

En esta página, se describe cómo administrar el ciclo de vida de una operación de larga duración (LRO) en AI Applications.

Se devuelve un objeto de operación de larga duración cuando una llamada a un método puede tardar mucho tiempo en completarse. Por ejemplo, la API de AI Applications crea una operación de larga duración cuando llamas a documents.import a través de la API o las bibliotecas cliente. La operación hace un seguimiento del estado del trabajo de procesamiento.

Puedes usar los métodos de operaciones de larga duración que proporciona la API de AI Applications para verificar el estado de las operaciones. También puedes enumerar o sondear operaciones.

El registro de una operación se conserva aproximadamente 30 días después de que esta finaliza, lo que significa que no puedes ver ni enumerar una operación después de ese tiempo.

Enumerar las operaciones de larga duración

A continuación, se muestra cómo enumerar las operaciones de un recurso Google Cloud.

REST

Para enumerar las operaciones de larga duración de un recurso Google Cloud , sigue este paso:

  • Llama al método operations.list de la siguiente forma:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/operations"

    DATA_STORE_ID: Es el ID del almacén de datos de AI Applications que se creó con tu motor. En la URL de la consola de Google Cloud , el ID del almacén de datos aparece después de engines/ y antes de /data.

Python

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

Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

from typing import Optional

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_PROCESSOR_LOCATION"  # Options: "global"
# search_engine_id = "YOUR_SEARCH_ENGINE_ID"

# Create filter in https://google.aip.dev/160 syntax
# operations_filter = "YOUR_FILTER"


def list_operations_sample(
    project_id: str,
    location: str,
    search_engine_id: str,
    operations_filter: Optional[str] = None,
) -> operations_pb2.ListOperationsResponse:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # The full resource name of the search engine branch.
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{search_engine_id}"

    # Make ListOperations request
    request = operations_pb2.ListOperationsRequest(
        name=name,
        filter=operations_filter,
    )

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

    # Print the Operation Information
    for operation in response.operations:
        print(operation)

    return response

Obtén detalles sobre una operación de larga duración

A continuación, se muestra cómo obtener detalles sobre una operación.

REST

Para obtener el estado de una operación de larga duración y ver sus detalles, sigue estos pasos:

  1. Busca el nombre de la operación de una de las siguientes dos maneras:

    • Después de llamar a un método que devuelve una operación de larga duración, revisa la respuesta.

      Por ejemplo, si llamas a documents.import, el comienzo de la respuesta se verá de la siguiente manera:

      {
  "operations": [
    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata",
      }
    }
  ]
}

      El valor name en la respuesta proporciona el nombre de la operación, que se puede usar para consultar el estado de la operación. No incluyas las comillas cuando copies el nombre de la operación.

    • Obtén el nombre de la operación enumerando las operaciones de larga duración.

  2. Llama al método operations.get en el recurso que creó la operación:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"

    OPERATION_NAME: Proporciona el nombre de la operación sobre la que necesitas información. Puedes encontrar el nombre de la operación si enumeras las operaciones de larga duración.

    Las primeras líneas de la respuesta del comando GET deberían verse de la siguiente manera:

    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata"
      }
    }

Python

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

Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def get_operation_sample(operation_name: str) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)
    operation = client.get_operation(request=request)

    # Print the Operation Information
    print(operation)

    return operation

Sondea una operación de larga duración

A continuación, se muestra cómo sondear el estado de una operación.

REST

Para sondear la operación de larga duración hasta que finalice, sigue estos pasos:

  1. Ejecuta el siguiente comando, que llama al método operations.get de forma repetida, con una retirada de 10 segundos entre cada solicitud:

    while true; \
    do curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"; \
    sleep 10; \
    done

    OPERATION_NAME: Proporciona el nombre de la operación que deseas sondear. Puedes encontrar el nombre de la operación si enumeras las operaciones de larga duración. Por ejemplo, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  2. Detén el trabajo de sondeo (Control+Z) después de que el estado muestre "done": true.

Python

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

Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

from time import sleep

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def poll_operation_sample(
    operation_name: str, limit: int = 10
) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)

    for _ in range(limit):
        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)

    return operation

Cancelar una operación de larga duración

A continuación, se muestra cómo cancelar una operación:

REST

Para cancelar una operación de larga duración, sigue estos pasos:

  • Llama al método operations.cancel de la siguiente forma:

    curl -X post \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/OPERATION_NAME":cancel

    OPERATION_NAME: Proporciona el nombre de la operación que deseas cancelar. Puedes encontrar el nombre de la operación si enumeras las operaciones de larga duración. Por ejemplo, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

    Después de que se realiza la llamada a la API, el servidor intenta cancelar la operación. Los resultados que verás y las acciones que puedes realizar son los siguientes:

    • Un error con "code": 400 y "status": "FAILED_PRECONDITION" indica que no se pudo cancelar la solicitud.

    • Una cancelación exitosa genera un objeto JSON vacío. Para verificar la cancelación, haz lo siguiente:

      • Usa el método operations.get.

      • Si la operación se cancela correctamente, la respuesta del método operations.get tiene el error "code": 1, que representa el código de estado CANCELLED.

        Por ejemplo:

        {
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.ImportDocumentsMetadata",
    "createTime": "2025-04-28T21:29:21.199190Z",
    "updateTime": "2025-04-28T21:31:29.076865Z"
  },
  "done": true,
  "error": {
    "code": 1,
    "message": "Operation projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789 is cancelled."
  }
}

Python

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

Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def cancel_operation_sample(operation_name: str) -> None:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make CancelOperation request
    request = operations_pb2.CancelOperationRequest(name=operation_name)
    client.cancel_operation(request=request)

    return