Lang andauernde Vorgänge überwachen

Auf dieser Seite wird beschrieben, wie Sie den Lebenszyklus eines lang laufenden Vorgangs (Long-Running Operation, LRO) in AI Applications verwalten.

Ein Vorgang mit langer Ausführungszeit-Objekt wird zurückgegeben, wenn ein Aufruf einer Methode sehr lange dauern kann. Wenn Sie beispielsweise documents.import über die AI Applications API oder die Clientbibliotheken aufrufen, wird ein Vorgang mit langer Ausführungszeit erstellt. Der Vorgang verfolgt den Status des Verarbeitungsjobs.

Sie können die Methoden für Vorgänge mit langer Ausführungszeit verwenden, die von der AI Applications API bereitgestellt werden, um den Status der Vorgänge zu prüfen. Sie können auch Vorgänge auflisten oder abfragen.

Der Datensatz eines Vorgangs wird für etwa 30 Tage gespeichert, nachdem der Vorgang abgeschlossen wurde. Dies bedeutet, dass Sie nach diesem Zeitpunkt den Vorgang nicht mehr aufrufen oder auflisten können.

Lange laufende Vorgänge auflisten

Im Folgenden wird gezeigt, wie Sie die Vorgänge für eine Google Cloud-Ressource auflisten.

REST

So listen Sie die Vorgänge mit langer Ausführungszeit für eine Google Cloud -Ressource auf:

  • Rufen Sie die Methode operations.list auf.

    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: Die ID des AI Applications-Datenspeichers, der mit Ihrer Engine erstellt wurde. In der Google Cloud Konsolen-URL wird die Datenspeicher-ID nach engines/ und vor /data angezeigt.

Python

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Python API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Details zu einem Vorgang mit langer Ausführungszeit abrufen

Im Folgenden wird gezeigt, wie Sie Details zu einem Vorgang abrufen.

REST

So rufen Sie den Status und die Details eines lang andauernden Vorgangs auf:

  1. Sie können den Namen des Vorgangs auf zwei Arten ermitteln:

    • Nachdem Sie eine Methode aufgerufen haben, die einen Vorgang mit langer Ausführungszeit zurückgibt, sehen Sie sich die Antwort an.

      Wenn Sie beispielsweise documents.import aufrufen, sieht der Anfang der Antwort so aus:

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

      Der Wert name in der Antwort enthält den Vorgangsnamen, mit dem der Vorgangsstatus abgefragt werden kann. Kopieren Sie den Vorgangsnamen ohne Anführungszeichen.

    • Rufen Sie den Vorgangsnamen ab, indem Sie Vorgänge mit langer Ausführungszeit auflisten.

  2. Rufen Sie die Methode operations.get für die Ressource auf, mit der der Vorgang erstellt wurde:

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

    OPERATION_NAME: Geben Sie den Namen des Vorgangs an, zu dem Sie Informationen benötigen. Sie können den Vorgangsnamen durch Auflisten von Vorgängen mit langer Ausführungszeit ermitteln.

    Die ersten Zeilen der Antwort des GET-Befehls sehen in etwa so aus:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Python API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Lang andauernden Vorgang abfragen

Im Folgenden wird gezeigt, wie Sie den Status eines Vorgangs abrufen.

REST

So fragen Sie den Vorgang mit langer Ausführungszeit ab, bis er abgeschlossen ist:

  1. Führen Sie den folgenden Befehl aus, mit dem die Methode operations.get wiederholt aufgerufen wird. Zwischen den einzelnen Anfragen wird ein Backoff von 10 Sekunden verwendet:

    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: Geben Sie den Namen des Vorgangs an, den Sie abfragen möchten. Sie können den Vorgangsnamen durch Auflisten von Vorgängen mit langer Ausführungszeit ermitteln. Beispiel: projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789

  2. Beenden Sie den Polling-Job (Control+Z), nachdem der Status "done": true lautet.

Python

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Python API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Lange laufenden Vorgang abbrechen

Im Folgenden wird gezeigt, wie Sie einen Vorgang abbrechen:

REST

So brechen Sie einen langwierigen Vorgang ab:

  • Rufen Sie die Methode operations.cancel auf.

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

    OPERATION_NAME: Geben Sie den Namen des Vorgangs an, den Sie abbrechen möchten. Sie können den Vorgangsnamen durch Auflisten von Vorgängen mit langer Ausführungszeit ermitteln. Beispiel: projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789

    Nach dem API-Aufruf versucht der Server, den Vorgang abzubrechen. Die Ergebnisse, die Sie sehen, und die Aktionen, die Sie ausführen können, sind wie folgt:

    • Ein Fehler mit "code": 400 und "status": "FAILED_PRECONDITION" gibt an, dass die Anfrage nicht abgebrochen werden konnte.

    • Bei einer erfolgreichen Kündigung wird ein leeres JSON-Objekt zurückgegeben. So prüfen Sie die Kündigung:

      • Verwenden Sie die Methode operations.get.

      • Wenn der Vorgang erfolgreich abgebrochen wurde, enthält die Antwort der Methode operations.get den Fehler "code": 1, der dem Statuscode CANCELLED entspricht.

        Beispiel:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Python API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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