Monitorare le operazioni a lunga esecuzione

Questa pagina descrive come gestire il ciclo di vita di un'operazione a lunga esecuzione (LRO) in Agent Search.

Un oggetto operazione a lunga esecuzione viene restituito quando una chiamata a un metodo potrebbe richiedere molto tempo per essere completata. Ad esempio, l'API Discovery Engine crea un'operazione a lunga esecuzione quando chiami documents.import tramite l'API o le librerie client. L'operazione tiene traccia dello stato del job di elaborazione.

Puoi utilizzare i metodi delle operazioni a lunga esecuzione forniti dall'API Discovery Engine per controllare lo stato delle operazioni. Puoi anche elencare o eseguire il polling delle operazioni.

Il record di un'operazione viene conservato per circa 30 giorni dopo il completamento dell'operazione, il che significa che non puoi visualizzare o elencare un'operazione dopo questo periodo.

Elenca operazioni a lunga esecuzione

Di seguito viene mostrato come elencare le operazioni per una Google Cloud risorsa.

REST

Per elencare le operazioni a lunga esecuzione per una Google Cloud risorsa, segui questo passaggio:

  • Chiama il operations.list metodo:

    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: l'ID del datastore di Agent Search creato con il tuo motore. Nell' Google Cloud URL della console, l'ID del datastore viene visualizzato dopo engines/ e prima di /data.

Python

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Agent Search.

Per eseguire l'autenticazione in Agent Search, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Visualizza i dettagli di un'operazione a lunga esecuzione

Di seguito viene mostrato come visualizzare i dettagli di un'operazione.

REST

Per visualizzare lo stato e i dettagli di un'operazione a lunga esecuzione:

  1. Trova il nome dell'operazione in uno dei due modi seguenti:

    • Dopo aver effettuato una chiamata a un metodo che restituisce un'operazione a lunga esecuzione, esamina la risposta.

      Ad esempio, se chiami documents.import, l'inizio della risposta sarà simile al seguente:

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

      Il valore name nella risposta fornisce il nome dell'operazione, che può essere utilizzato per eseguire query sullo stato dell'operazione. Non includere le virgolette quando copi il nome dell'operazione.

    • Recupera il nome dell'operazione elencando le operazioni a lunga esecuzione.

  2. Chiama il operations.get metodo sulla risorsa che ha creato l'operazione:

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

    OPERATION_NAME: fornisci il nome dell'operazione per cui ti servono informazioni. Puoi trovare il nome dell'operazione elencando le operazioni a lunga esecuzione.

    Le prime righe della risposta del comando GET saranno simili a queste:

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

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Agent Search.

Per eseguire l'autenticazione in Agent Search, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Esegui il polling di un'operazione a lunga esecuzione

Di seguito viene mostrato come eseguire il polling dello stato di un'operazione.

REST

Per eseguire il polling dell'operazione a lunga esecuzione fino al completamento:

  1. Esegui il seguente comando, che chiama ripetutamente il metodo operations.get, utilizzando un backoff di 10 secondi tra una richiesta e l'altra:

    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: fornisci il nome dell'operazione di cui vuoi eseguire il polling. Puoi trovare il nome dell'operazione elencando le operazioni a lunga esecuzione. Ad esempio, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  2. Interrompi il job di polling (Control+Z) dopo che lo stato mostra "done": true.

Python

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Agent Search.

Per eseguire l'autenticazione in Agent Search, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Annulla un'operazione a lunga esecuzione

Di seguito viene mostrato come annullare un'operazione:

REST

Per annullare un'operazione a lunga esecuzione:

  • Chiama il operations.cancel metodo:

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

    OPERATION_NAME: fornisci il nome dell'operazione che vuoi annullare. Puoi trovare il nome dell'operazione elencando le operazioni a lunga esecuzione. Ad esempio, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

    Dopo aver effettuato la chiamata API, il server tenta di annullare l'operazione. I risultati visualizzati e le azioni che puoi intraprendere sono i seguenti:

    • Un errore con "code": 400 e "status": "FAILED_PRECONDITION" indica che la richiesta non può essere annullata.

    • Un annullamento riuscito genera un oggetto JSON vuoto. Per verificare l'annullamento:

      • Utilizza il operations.get metodo.

      • Se l'operazione viene annullata correttamente, la risposta del operations.get metodo contiene l'errore "code": 1, che rappresenta il CANCELLED codice di stato.

        Ad esempio:

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

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Agent Search.

Per eseguire l'autenticazione in Agent Search, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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