Monitora le operazioni a lunga esecuzione

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

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 AI Applications crea un'operazione a lunga esecuzione quando chiami documents.import tramite l'API o le librerie client. L'operazione monitora lo stato del job di elaborazione.

Puoi utilizzare i metodi di operazioni a lunga esecuzione forniti dall'API AI Applications 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 di tempo.

Elenca operazioni a lunga esecuzione

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

REST

Per elencare le operazioni di lunga durata per una risorsa Google Cloud , segui questo passaggio:

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

Python

Per saperne di più, consulta la documentazione di riferimento dell'API AI Applications per Python.

Per autenticarti in AI Applications, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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

Visualizzare i dettagli di un'operazione a lunga esecuzione

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

REST

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

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

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

      Ad esempio, se chiami documents.import, l'inizio della risposta è 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 metodo operations.get 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 hai bisogno di informazioni. Puoi trovare il nome dell'operazione elencando le operazioni a lunga esecuzione.

    Le prime righe della risposta del comando GET hanno il seguente aspetto:

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

Per autenticarti in AI Applications, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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

Eseguire 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 termine, segui questi passaggi:

  1. Esegui il seguente comando, che chiama il metodo operations.get ripetutamente, 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 che vuoi interrogare. 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 AI Applications per Python.

Per autenticarti in AI Applications, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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 illustrato come annullare un'operazione:

REST

Per annullare unoperazione a lunga esecuzione:

  • Chiama il metodo operations.cancel:

    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 è stata annullata.

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

      • Utilizza il metodo operations.get.

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

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

Per autenticarti in AI Applications, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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