Surveiller les opérations de longue durée

Cette page explique comment gérer le cycle de vie d'une opération de longue durée (LRO) dans Gemini Enterprise.

Un objet d'opération de longue durée est renvoyé lorsqu'un appel à une méthode peut prendre un certain temps. Par exemple, l'API Gemini Enterprise crée une opération de longue durée lorsque vous appelez documents.import via l'API ou les bibliothèques clientes. L'opération suit l'état du job de traitement.

Vous pouvez utiliser les méthodes d'opérations de longue durée fournies par l'API Gemini Enterprise pour vérifier l'état des opérations. Vous pouvez également répertorier ou interroger des opérations.

L'enregistrement d'une opération est conservé pendant environ 30 jours après la fin de l'opération. Cela signifie que vous ne pouvez pas afficher ni répertorier une opération après ce délai.

Répertorier les opérations de longue durée

Les exemples suivants montrent comment répertorier les opérations d'une Google Cloud ressource.

REST

Pour répertorier les opérations de longue durée d'une Google Cloud ressource, procédez comme suit :

  • Appelez la operations.list méthode :

    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 du data store Gemini Enterprise créé avec votre moteur. Dans l'URL de la Google Cloud console, l'ID du data store apparaît après engines/ et avant /data.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide de Gemini Enterprise à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Python Gemini Enterprise.

Pour vous authentifier auprès de Gemini Enterprise, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Obtenir des informations sur une opération de longue durée

Les exemples suivants montrent comment obtenir des informations sur une opération.

REST

Pour connaître l'état d'une opération de longue durée et afficher des informations à son sujet, procédez comme suit :

  1. Recherchez le nom de l'opération de l'une des deux manières suivantes :

    • Après avoir appelé une méthode qui renvoie une opération de longue durée, examinez la réponse.

      Par exemple, si vous appelez documents.import, le début de la réponse se présente comme suit :

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

      La valeur name de la réponse fournit le nom de l'opération, qui peut être utilisé pour interroger l'état de l'opération. N'incluez pas les guillemets lorsque vous copiez le nom de l'opération.

    • Obtenez le nom de l'opération en répertoriant les opérations de longue durée.

  2. Appelez la operations.get méthode sur la ressource qui a créé l'opération :

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

    OPERATION_NAME: indiquez le nom de l'opération pour laquelle vous avez besoin d'informations. Vous pouvez trouver le nom de l'opération en répertoriant les opérations de longue durée.

    Les premières lignes de la réponse de la commande GET se présentent comme suit :

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

Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide de Gemini Enterprise à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Python Gemini Enterprise.

Pour vous authentifier auprès de Gemini Enterprise, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Interroger une opération de longue durée

Les exemples suivants montrent comment interroger l'état d'une opération.

REST

Pour interroger l'opération de longue durée jusqu'à ce qu'elle se termine, procédez comme suit :

  1. Exécutez la commande suivante, qui appelle la operations.get méthode de manière répétée, avec un intervalle de 10 secondes entre chaque requête :

    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: indiquez le nom de l'opération que vous souhaitez interroger. Vous pouvez trouver le nom de l'opération en répertoriant les opérations de longue durée. Par exemple, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  2. Arrêtez le job d'interrogation (Control+Z) une fois que l'état affiche "done": true.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide de Gemini Enterprise à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Python Gemini Enterprise.

Pour vous authentifier auprès de Gemini Enterprise, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Annuler une opération de longue durée

Pour annuler une opération, procédez comme suit :

REST

Pour annuler une opération de longue durée, procédez comme suit :

  • Appelez la operations.cancel méthode :

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

    OPERATION_NAME: indiquez le nom de l'opération que vous souhaitez annuler. Vous pouvez trouver le nom de l'opération en répertoriant les opérations de longue durée. Par exemple, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

    Une fois l'appel d'API effectué, le serveur tente d'annuler l'opération. Les résultats que vous voyez et les actions que vous pouvez effectuer sont les suivants :

    • Une erreur avec "code": 400 et "status": "FAILED_PRECONDITION" indique que la requête n'a pas pu être annulée.

    • Une annulation réussie génère un objet JSON vide. Pour vérifier l'annulation :

      • Utilisez la operations.get méthode.

      • Si l'opération est annulée, la réponse de la operations.get méthode comporte l'erreur "code": 1, qui représente le CANCELLED code d'état.

        Exemple :

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

Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide de Gemini Enterprise à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Python Gemini Enterprise.

Pour vous authentifier auprès de Gemini Enterprise, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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