Supervisa 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 Agent Search.

Se muestra 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 Discovery Engine 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 realiza un seguimiento del estado del trabajo de procesamiento.

Puedes usar los métodos de operaciones de larga duración que proporciona la API de Discovery Engine 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.

Enumera las operaciones de larga duración

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

REST

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

  • Llama al operations.list método:

    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 Agent Search 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 PythonAgent Search.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para 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. Encuentra el nombre de la operación de una de las siguientes maneras:

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

      Por ejemplo, si llamas a documents.import, el inicio 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 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.

    • Para obtener el nombre de la operación, enumera las operaciones de larga duración.

  2. Llama al operations.get método 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 para la que necesitas información. Para encontrar el nombre de la operación, enumera las operaciones de larga duración.

    Las primeras líneas de la respuesta del comando GET se verán 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 PythonAgent Search.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para 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 operations.get método 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. Para encontrar el nombre de la operación, enumera 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 PythonAgent Search.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para 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

Cancela 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 operations.cancel método:

    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. Para encontrar el nombre de la operación, enumera 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 realizar la llamada a la API, el servidor intenta cancelar la operación. Los resultados que ves 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 correcta da como resultado un objeto JSON vacío. Para verificar la cancelación, haz lo siguiente:

      • Usa el operations.get método.

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

        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 PythonAgent Search.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para 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