Lang andauernde Vorgänge überwachen

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

Ein Objekt vom Typ Long-Running Operation wird zurückgegeben, wenn ein Methodenaufruf sehr lange dauern kann. Die AI Applications API erstellt beispielsweise einen Vorgang mit langer Ausführungszeit, wenn Sie documents.import über die API oder Clientbibliotheken aufrufen. 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 lange laufenden Vorgänge 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 Datenspeichers für KI-Anwendungen, der mit Ihrer Engine erstellt wurde. In der Google Cloud Console-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 KI-Anwendungen 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 lang andauernden Vorgang abrufen

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

REST

So rufen Sie den Status und Details zu einem lang andauernden Vorgang auf:

  1. Sie haben zwei Möglichkeiten, den Namen des Vorgangs zu ermitteln:

    • Nachdem Sie eine Methode aufgerufen haben, die einen lang andauernden Vorgang zurückgibt, prüfen Sie die Antwort.

      Wenn du beispielsweise documents.import aufrufst, sieht der Anfang der Antwort in etwa 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 ist der Vorgangsname, mit dem der Vorgangsstatus abgefragt werden kann. Kopieren Sie den Vorgangsnamen ohne Anführungszeichen.

    • Sie können den Vorgangsnamen abrufen, 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, für den Sie Informationen benötigen. Sie können den Vorgangsnamen ermitteln, indem Sie lange laufende Vorgänge auflisten.

    Die ersten Zeilen der Antwort des Befehls GET 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 KI-Anwendungen 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 der Status eines Vorgangs abgefragt wird.

REST

So können Sie den Vorgang mit langer Ausführungszeit so lange abfragen, bis er abgeschlossen ist:

  1. Führen Sie den folgenden Befehl aus, um die Methode operations.get wiederholt aufzurufen und dabei zwischen den einzelnen Anfragen einen Backoff von 10 Sekunden zu verwenden:

    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 ermitteln, indem Sie lange laufende Vorgänge auflisten. Beispiel: projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789

  2. Beenden Sie den Abfragejob (Control+Z), wenn der Status "done": true lautet.

Python

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

Richten Sie zur Authentifizierung bei KI-Anwendungen 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

So brechen Sie einen Vorgang ab:

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 ermitteln, indem Sie lange laufende Vorgänge auflisten. 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 folgenden Ergebnisse und Aktionen sind möglich:

    • Ein Fehler bei "code": 400 und "status": "FAILED_PRECONDITION" weist darauf hin, dass die Anfrage nicht storniert werden konnte.

    • Bei einer erfolgreichen Kündigung wird ein leeres JSON-Objekt zurückgegeben. So bestätigen 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 KI-Anwendungen 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