Monitorizar operaciones de larga duración

En esta página se describe cómo gestionar el ciclo de vida de una operación de larga duración (OLD) en aplicaciones de IA.

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

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

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

Crear una lista de 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 Google Cloud recurso, sigue este paso:

  • Llama al método operations.list:

    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: ID del almacén de datos de aplicaciones de IA que se creó con tu motor. En la URL de la consola, el ID del almacén de datos aparece después de engines/ y antes de /data. Google Cloud

Python

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

Para autenticarte en las aplicaciones de IA, 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. 

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

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

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

REST

Para consultar el estado y los detalles de una operación de larga duración, sigue estos pasos:

  1. Busca el nombre de la operación de una de estas dos formas:

    • 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 inicio de la respuesta tiene un aspecto similar al siguiente:

      {
  "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 de 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 ha creado 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 de la que necesitas información. Para encontrar el nombre de la operación, consulta la sección sobre cómo listar operaciones de larga duración.

    Las primeras líneas de la respuesta del comando GET tienen un aspecto similar al siguiente:

    {
      "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 AI Applications Python.

Para autenticarte en las aplicaciones de IA, 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. 

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

Sondear 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 repetidamente, con un tiempo de espera 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: indica el nombre de la operación que quieras consultar. Para encontrar el nombre de la operación, consulta la sección sobre cómo listar 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. Detiene la tarea de comprobación (Control+Z) cuando el estado sea "done": true.

Python

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

Para autenticarte en las aplicaciones de IA, 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. 

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:

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

    OPERATION_NAME: indica el nombre de la operación que quieres cancelar. Para encontrar el nombre de la operación, consulta la sección sobre cómo listar operaciones de larga duración. Por ejemplo, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

    Una vez que se ha hecho la llamada a la API, el servidor intenta cancelar la operación. Estos son los resultados que verás y las acciones que puedes llevar a cabo:

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

    • Si la cancelación se realiza correctamente, se devuelve un objeto JSON vacío. Para verificar la cancelación:

      • 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 AI Applications Python.

Para autenticarte en las aplicaciones de IA, 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. 

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