Monitor long-running operations

Stay organized with collections Save and categorize content based on your preferences.

REST

To list the long-running operations for a Google Cloud resource, follow this step:

• Call the operations.list method:

  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: The ID of the AI Applications data store that was created with your engine. In the Google Cloud console URL, the data store ID appears after engines/ and before /data.

Python

For more information, see the AI Applications Python API reference documentation.

To authenticate to AI Applications, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

REST

To get the status of and view details about a long-running operation, follow these steps:

1. Find the name of the operation in one of two ways:

   • After you've made a call to a method that returns a long-running operation, review the response.

     For example, if you call documents.import, the start of the response looks something like this:

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

     The name value in the response provides the operation name, which can be used to query the operation status. Don't include the quotes when you copy the operation name.

   • Get the operation name by listing long-running operations.

2. Call the operations.get method on the resource that created the operation:

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

   OPERATION_NAME: Provide the name of the operation for which you need information. You can find the operation name by listing long-running operations.

   The first lines of the response from the GET command look something like this:

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

For more information, see the AI Applications Python API reference documentation.

To authenticate to AI Applications, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

REST

To poll the long-running operation until it finishes, follow these steps:

1. Run the following command, which calls the operations.get method repeatedly, using a backoff of 10 seconds between each request:

   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: Provide the name of the operation you want to poll. You can find the operation name by listing long-running operations. For example, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

2. Stop the polling job (Control+Z) after the status shows "done": true.

Python

For more information, see the AI Applications Python API reference documentation.

To authenticate to AI Applications, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

REST

To cancel a long-running operation, follow these steps:

• Call the operations.cancel method:

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

  OPERATION_NAME: Provide the name of the operation you want to cancel. You can find the operation name by listing long-running operations. For example, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  After the API call is made, the server attempts to cancel the operation. The results you see and the actions you can take are as follows:

  • An error with "code": 400 and "status": "FAILED_PRECONDITION" indicates that the request couldn't be canceled.

  • A successful cancellation results in an empty JSON object. To verify the cancellation:

    • Use the operations.get method.

    • If the operation is successfully cancelled, the response from the operations.get method has the error "code": 1, which represents the CANCELLED status code.

      For example:

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

For more information, see the AI Applications Python API reference documentation.

To authenticate to AI Applications, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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